{"openapi": "3.0.0", "info": {"title": "Public REST API", "version": "v1", "description": "All the endpoints below have a prefix of `https://gate.safari.tech/api/v1/` (e.g. `POST https://gate.safari.tech/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 <secret key>`.\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://gate.safari.tech/apis/plugins/WooCommerce%20v3.5+), [OpenCart](https://gate.safari.tech/apis/plugins/OpenCart%20v3.0+), [Magento](https://gate.safari.tech/apis/plugins/Magento%20v2.0+), [PrestaShop](https://gate.safari.tech/apis/plugins/PrestaShop%20v1.7+)\n\n\n\nLibraries: [PHP](https://gate.safari.tech/apis/libraries/PHP), [Java](https://gate.safari.tech/apis/libraries/Java), [C#](https://gate.safari.tech/apis/libraries/C%23), [Node.js](https://gate.safari.tech/apis/libraries/Node.js)\n\nSDKs: [iOS](https://gate.safari.tech/apis/sdks/iOS), [Android](https://gate.safari.tech/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/<purchase_id>/` 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## Custom checkout \u2014 Client side (Direct Post)\n\nDirect post integration allows running payments through the custom payment flow.\n\nTo accept payments in your application or website, use `POST /purchases/` request to create a `Purchase`.\n\nTo capture customers card details use an HTML `<form>` hosted on your website with `method=\"POST\"` and `action` pointing to the `direct_post_url` of the transaction.\n\nYou will also need to fill the form with `<input>`'s for the fields with card details. As a result, when a customer submits their card details, it will be posted straight to our system, allowing you to customize the checkout as you wish. At the same time, your PCI DSS requirement is only raised to Self-Assessment Questionnaire (SAQ A-EP), as your system doesn't receive or process card data.\n\nFor more details, see the documentation on Purchase's `direct_post_url` field.\n\n### Tokenization & recurring payments\n\nYou can store card tokens and charge the respective cards without user interaction if the payment channel supports tokenization.\n\nWhen you pass `remember_card=on` to `direct_post_url`, the respective `Purchase`'s ID will serve as a card token. This initial `Purchase` will have the `is_recurring_token` field set to `true`.\n\nTo charge the tokenized card once again, create a new Purchase and then call the `POST /purchases/{new_purchase_id}/charge/`. In the request body, provide `\"recurring_token\": \"initial_purchase_id\"`. When the request succeeds (response code `200`), the new Purchase will become paid. The token will be persisted in the Purchase's recurring_token field.\n\nUse `\"recurring_token\": \"initial_purchase_id\"` in all the upcoming `POST /purchases/{new_purchase_id}/charge/` requests.\n\nIf you wish to delete the recurring token stored for the initial `Purchase`, use the `POST /purchases/{initial_purhcase_id}/delete_recurring_token/` request. Its `is_recurring_token` will reset to `false`. \n\n## Custom checkout \u2014 Server side (Server-to-Server)\n\nServer-to-Server (\"S2S\") integration allows running payments on the server level without direct interaction between the client\u2019s browser or application and API.\n\nYou can build an integration that prevents payers from accessing platform resources directly. In this flow, 3D Secure implementation allows API clients to:\n\nCheck 3D Secure enrolment, and if the card is enrolled, receive ACS URL together with all the necessary params for redirection to ACS (PaReq, MD);\nRedirect the payer to the ACS system of their issuer bank;\nReceive the payer back and execute the authorization with a separate request.\n\nIf the card is not enrolled in 3D Secure, authorization will execute synchronously.\n\nPlease note that 3DSv2 which is now the industry standard is fully supported by the S2S flow. While PaReq/PaRes below are 3DSv1 parameters (replaced by creq/cres in 3DSv2 challenge), in case of 3DSv2 proxy ACS solution (where the system is accepting the cardholder navigation using 3DSv1 flow and is performing all parts of 3DSv2 verification and challenge on behalf of merchant) is implemented to maintain API compatibility for older integrations.\n\nTo accept payments in your application or website via S2S:\n\n1.  Ensure the Purchase is created as described in Custom payment flow \u2014 Direct Post. As per the Purchase's direct_post_url field description, you will need to ensure all the necessary criteria are met, including success_redirect/failure_redirect fields defined for Purchase and set to arbitrary valid URLs (they will not receive any redirects in the S2S scenario);\n2.  Implement the following request in your server code, appending \"?s2s=true\" to direct_post_url to form the resulting endpoint (you can obtain the S2S token value from your account manager):\n\n        POST {direct_post_url}?s2s=true\n\n    Specify the following headers:\n\n        Content-Type: application/json\n        Authorization: Bearer {S2S token}\n\n    In the request body, provide the following data in JSON (you can omit some of the fields, then system will use default values; We recommend providing correct values from the user\u2019s browser as it can affect 3D Secure success rate):\n\n        {\n          \"cardholder_name\": \"John Doe\",\n          \"card_number\": \"4444333322221111\",\n          \"expires\": \"01/23\",\n          \"cvc\": \"123\",\n          \"remember_card\": \"on\",\n          \"remote_ip\": \"8.8.8.8\",\n          \"user_agent\": \"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36\",\n          \"accept_header\": \"text/html\",\n          \"language\": \"en-US\",\n          \"java_enabled\": false,\n          \"javascript_enabled\": true,\n          \"color_depth\": 24,\n          \"utc_offset\": 0,\n          \"screen_width\": 1920,\n          \"screen_height\": 1080\n        }\n\n    |Field name&nbsp;|Required&nbsp;|Validation criteria/remarks&nbsp;|Default value|\n    |--- |--- |---|--- |\n    |cardholder_name|Y|Latin letters only (space and apostrophe ('), dot (.), dash (-) symbols are also allowed), max 45 characters||\n    |card_number|Y|text, digits only, no whitespace, max 19 characters||\n    |expires|Y|text in 'MM/YY' format, digits and a slash only (/^\\\\d{2}\\\\/\\\\d{2}$/), max 5 characters||\n    |cvc|Y|numeric string of 3 or 4 digits||\n    |remember_card|N|literal value \"on\" to save card, any other string otherwise||\n    |remote_ip|Y|external IP of payer\u2019s browser in IPv4 or IPv6 format||\n    |user_agent|N|User-Agent as sent by the payer\u2019s browser, max 2048 charge|Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/ 537.36 (KHTML, like Gecko) Chrome/ 88.0.4324.96 Safari/ 537.36|\n    |accept_header|N|Same as above, max 2048 characters|text/html|\n    |language|N|Same as above, max 8 characters|en-US|\n    |java_enabled|N|boolean|false|\n    |javascript_enabled|N|boolean|true|\n    |color_depth|N|integer in 0-255 range|24|\n    |utc_offset|N|integer in -32,768 to 32,767 range|0|\n    |screen_width|N|integer in uint64 range|1920|\n    |screen_height|N|integer in uint64 range|1080|\n\n3.  If the card is not enrolled in 3S Secure, then a response will contain the field \"status\" with one of the following values:\n\"executed\" in case of a successful payment authorization;\n\"authorized\" in case fund reservation using Purchase.skip_capture was requested;\n\"pending\" in case the acquirer was not able to provide final status yet (in this case you need to await a Webhook callback);\n\"error\" in case of an authorization error.\n\n    Example:\n\n        {\"status\": \"executed\"}\n\n    You will receive \"executed\", \"authorized\" or \"pending\" statuses with a response status code 200 and \"error\" status - with a status code of 400.\n\n    In all of those cases, it is necessary to set up webhooks for purchase events (`purchase.paid, purchase.payment_failure` at least) to receive further information about the status of the financial transaction.\n\n4.  If the card is enrolled in 3D Secure, the response will have a status code of 200, the status will be 3DS_required, and the response will contain additional fields:\n\n        {\n          \"status\": \"3DS_required\",\n          \"Method\": \"(POST|GET)\",\n          \"PaReq\": \"...\",\n          \"MD\": \"... (can arrive empty)\",\n          \"URL\": \"http://url.of.acs.bank/\",\n          \"callback_url\": \"https://...\"\n        }\n\n    It\u2019s necessary to ensure your client\u2019s browser makes a request with the method specified in `Method` (GET or POST only) to the ACS of issuer bank returned in \"URL\", including the values of `MD` and `PaReq` as received (use query params in case of GET and request body params in case of POST). Be aware that MD might arrive empty \u2013 in that case, you can send it further as an empty string.\n\n    In addition to those, you also **need to include the `TermUrl` parameter** in the client\u2019s browser request, pointing to the URL in your system where the customer\u2019s navigation will be expected. Once the payer approves the transaction, he will be redirected using the POST method to that URL with `MD` and `PaRes` params in the request body.\n\n5.  Once the client is back to `TermUrl` in your system and you have received the `MD` and `PaRes`, it\u2019s needed to transmit them to the platform to complete the authorization. Send the following request from your server code (no auth headers required):\n\n        POST {callback_url from step 4.}\n\n        Content-Type: application/x-www-form-urlencoded\n        MD={MD received, if any}&PaRes={PaRes received}\n\n    The response will contain the authorization status in JSON format and will be identical to the format described in section 3. Note: it's possible to receive a response code 400 to this request - e.g. in case the acquirer wasn't able to finalize the payment status yet. Please ignore that error response code and await a Purchase callback/final status instead. The same applies if you receive a \"pending\" status in response.\n\n## Testing Integration\n\nIt\u2019s possible to test-drive all checkouts using a test Purchase.\n\nFor a successful payment, you can use the following card numbers:\n\n*   4444 3333 2222 1111 - non-3D Secure card\n*   5555 5555 5555 4444 - 3D Secure card\n\nFor both cards, please use:\n\n*   any cardholder name\n*   any expiry larger or equal to the current month/year\n*   CVC = 123\n\nFor a failed payment, please change the CVC or expiration date.\n\nWhen using a 3D Secure enrolled card in S2S checkout,  an incorrect CVC will trigger an authorization failure on the S2S callback step (after the customer returns from test ACS). Using a wrong expiry date emulates data validation failure and results in immediate error before that step.\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/<billing_template_id>/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## <b id=\"callback-auth\">Authentication</b>\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": "test", "price": 100}]}, "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/<purchase_id>/` 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\nInstead of a redirect you can also utilize Direct Post checkout: you can create an HTML `<form>` on your website with `method=\"POST\"` and `action` pointing to `direct_post_url` of a created Purchase. You will also need to saturate form with `<input>`-s for card data fields. As a result, when a payer submits their card data, it will be posted straight to our system, allowing you to customize the checkout as you wish while your PCI DSS requirement is only raised to SAQ A-EP, as your system doesn't receive or process card data. For more details, see the documentation on Purchase's `direct_post_url` field.\n\nTo pay for test Purchases, use `4444 3333 2222 1111` as the card number, `123` as CVC, any date/month greater than now as expiry and any (Latin) cardholder name. Any other card number/CVC/expiry not greater or equal than the current month will all fail a test payment. ", "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": {"properties": {"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."}, "reference": {"type": "string", "maxLength": 128, "description": "Optional custom reference for the refund."}}}, "example": {"amount": 120, "reference": "REFUND-123"}}}}, "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\nConsult `refund_availability` field on Purchase on details whether this Purchase can be refunded or not.\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&currency=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`."}}}, "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"]}}}}}, "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&currency=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"]}}, "/payouts/": {"post": {"operationId": "payouts_create", "responses": {"201": {"$ref": "#/components/responses/Payout"}, "400": {"$ref": "#/components/responses/400"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Payout"}, "example": {"client": {"email": "test@example.com"}, "payment": {"amount": 10000, "currency": "EUR", "description": "This is a description"}, "brand_id": "f025d78f-3d23-49d1-a377-e2bf7e318a25"}}}}, "summary": "Create an unprocessed payout object. A separate request is needed to execute the payout.", "description": "To issue payouts in your application use `POST /payouts/` request to register a payout. Response will contain the payout execution url - `execution_url`. For card payouts send a POST request to `execution_url` with a JSON payload containing recipient's card details: \n\n`expiry_month`: string; 1-2 digits\n\n`expiry_year`: string; 1-2 digits, \n\n`card_number`: string; 16-19 chars, \n\n`cardholder_name`: string; 1-30 chars. <br><br>For wallet payouts, please contact support to get specific details on how to send a POST request to execution_url.<br><br>  You need to do the 2nd request within 15 minutes of creating the Payout object. Response will have a response code of 200 in case of payout initiation success (`status` attribute will be `executed` or `pending`) or an error code/message with a 400 error response code and `status` of `error`.\n\nFor response to the second request having a code of 200, status = `success` means that payout was already executed.\n\n Second request returning status of `pending` means the payout was accepted for processing but not executed yet. In this case, transaction processing can take up to 3-5 days depending on the payout provider. Once the processing will finish, `Payout.status` will change accordingly.\n\nIt's advised to subscribe to `payout.failed` and `payout.success` webhook events.\n\nTo test card Payouts, use `card_number` of 4444 3333 2222 1111, any `cardholder_name` and `expiry_month`/`expiry_year` equal or larger to the current ones.", "tags": ["Payouts"]}}, "/payouts/{id}/": {"parameters": [{"$ref": "#/components/parameters/id"}], "get": {"operationId": "payouts_read", "responses": {"200": {"$ref": "#/components/responses/Payout"}, "404": {"$ref": "#/components/responses/404"}}, "summary": "Retrieve an object by ID.", "tags": ["Payouts"]}}, "/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: <BillingTemplateClient object created>, 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: <BillingTemplateClient object created>, purchase: <Purchase object created>}`: 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"]}}, "/account/json/balance/": {"get": {"parameters": [{"$ref": "#/components/parameters/tokenized"}, {"in": "query", "name": "from", "description": "Retrieve a past balance value at a specific Unix timestamp", "schema": {"type": "integer"}}, {"$ref": "#/components/parameters/brand"}, {"$ref": "#/components/parameters/terminal_uid"}, {"$ref": "#/components/parameters/currency"}, {"$ref": "#/components/parameters/payment_method"}, {"$ref": "#/components/parameters/product"}, {"$ref": "#/components/parameters/flow"}, {"$ref": "#/components/parameters/country"}], "operationId": "balance", "responses": {"200": {"description": "Company balance successfully retrieved", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BalanceByCurrency"}}}}, "400": {"$ref": "#/components/responses/400"}}, "summary": "Get company balance.", "description": "Returns the company balance according to the provided query string filters. Multiple values can be provided for all filters except `from` and `to`, including all results matching any of these values.", "tags": ["Account"]}}, "/account/json/turnover/": {"get": {"parameters": [{"$ref": "#/components/parameters/tokenized"}, {"$ref": "#/components/parameters/from"}, {"$ref": "#/components/parameters/to"}, {"$ref": "#/components/parameters/brand"}, {"$ref": "#/components/parameters/terminal_uid"}, {"$ref": "#/components/parameters/currency"}, {"$ref": "#/components/parameters/payment_method"}, {"$ref": "#/components/parameters/product"}, {"$ref": "#/components/parameters/flow"}, {"$ref": "#/components/parameters/country"}], "operationId": "turnover", "responses": {"200": {"description": "Company turnover successfully retrieved", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TurnoverPair"}}}}, "400": {"$ref": "#/components/responses/400"}}, "summary": "Get company turnover.", "description": "Fetches the company turnover according to the provided query string filters. Must provide exactly one `currency` filter. Multiple values can be provided for all filters except `currency`, `from` and `to`, including all results matching any of these values.", "tags": ["Account"]}}, "/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 <a href=\"#model-Purchase\">Purchase<a> and <a href=\"#model-Payout\">Payout<a> 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 <a href=\"#model-PaymentMethod\">PaymentMethod<a> fro more information.", "schema": {"$ref": "#/components/schemas/PaymentMethod"}}, "product": {"in": "query", "name": "product", "description": "Filter result set to only include specified products(s). See <a href=\"#model-TransactionProduct\">TransactionProduct<a> 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 <a href=\"#model-TransactionFlow\">TransactionFlow<a> 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": {"Balance": {"type": "object", "description": "Company Balance in a specific currency", "properties": {"gross_balance": {"allOf": [{"$ref": "#/components/schemas/MoneyAmount"}, {"description": "Raw Company balance without any fees or reserved amounts subtracted"}]}, "balance": {"allOf": [{"$ref": "#/components/schemas/MoneyAmount"}, {"description": "Company gross balance with transaction fees subtracted"}]}, "available_balance": {"allOf": [{"$ref": "#/components/schemas/MoneyAmount"}, {"description": "Company balance currently available for withdrawal"}]}, "reserved": {"allOf": [{"$ref": "#/components/schemas/MoneyAmount"}, {"description": "Amount protected from withdrawal for an amount of time as per the brand configuration"}]}, "pending_outgoing": {"allOf": [{"$ref": "#/components/schemas/MoneyAmount"}, {"description": "Amount currently pending withdrawal"}]}, "fee_sell": {"$ref": "#/components/schemas/FeeSell"}}}, "BalanceByCurrency": {"type": "object", "description": "Map of currency to company Balance for the specific currency", "additionalProperties": {"$ref": "#/components/schemas/Balance"}, "example": {"EUR": {"balance": 93408, "fee_sell": 0, "reserved": 0, "gross_balance": 93408, "pending_outgoing": 0, "available_balance": 93408}, "RUB": {"balance": 1111840, "fee_sell": 360, "reserved": 0, "gross_balance": 1112200, "pending_outgoing": 0, "available_balance": 1111840}, "USD": {"balance": -35420, "fee_sell": 1880, "reserved": 0, "gross_balance": -33540, "pending_outgoing": 0, "available_balance": -35420}}}, "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: <purchase's 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- airtel: Airtel\n- american_express: American Express payment card\n- aronhub_redirect: Aronhub Redirect\n- beyounger_redirect: Beyounger Redirect\n- open_banking_a: Open Banking A\n- cybersource_hosted_checkout: Cybersource Hosted Checkout\n- discover: Discover payment card\n- ipsl_pgw: Ipsl Pgw\n- jcb: JCB payment card\n- jp_lapa: Jp Lapa\n- lapa_apgp: Apple/Google pay\n- lapa_redirect: Lapa Redirect\n- maestro: Maestro payment card\n- mastercard: Mastercard payment card\n- mtnmomo: Mtnmomo\n- payc_connection: Payc Connection\n- paytota_airtel: Paytota Airtel\n- paytota_mtnmomo: Paytota Mtnmomo\n- pne_apm_ap: Pne Apm Ap\n- pne_apm_gp: Pne Apm Gp\n- pne_apm_redirect: Pne Apm Redirect\n- safaricom: Safaricom\n- spago_redirect: Spago\n- troy: TROY payment card\n- unionpay: UnionPay payment card\n- unknown: Payment method could not be determinded\n- visa: Visa payment card", "enum": ["airtel", "american_express", "aronhub_redirect", "beyounger_redirect", "open_banking_a", "cybersource_hosted_checkout", "discover", "ipsl_pgw", "jcb", "jp_lapa", "lapa_apgp", "lapa_redirect", "maestro", "mastercard", "mtnmomo", "payc_connection", "paytota_airtel", "paytota_mtnmomo", "pne_apm_ap", "pne_apm_gp", "pne_apm_redirect", "safaricom", "spago_redirect", "troy", "unionpay", "unknown", "visa"]}, "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\n\n---\n\n`invalid_debtor_data`: Invalid debtor account data provided\n\n---\n\n`missing_purchase_personal_code`: Purchase personal code is required but was not set\n\n---\n\n`missing_purchase_full_name`: Purchase is missing the customer full name, which is required to proceed with this payment\n\n---\n\n`debtor_account_not_active`: The customer's banking account or profile is not fully active and cannot authorize the payment"}, "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}}}, "source_platform": {"type": "string", "nullable": true, "readOnly": true, "description": "An identifier of an external platform that created this object."}, "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 `<country_code> <number>` 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`."}, "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\n\n---\n\n`invalid_debtor_data`: Invalid debtor account data provided\n\n---\n\n`missing_purchase_personal_code`: Purchase personal code is required but was not set\n\n---\n\n`missing_purchase_full_name`: Purchase is missing the customer full name, which is required to proceed with this payment\n\n---\n\n`debtor_account_not_active`: The customer's banking account or profile is not fully active and cannot authorize the payment"}, "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"}]}, "pending_redirect": {"description": "When the provider redirects the customer back without providing a final payment status (Purchase is in `pending_execute` status), your customer will be taken to this link (see `pending_redirect_delay`). Otherwise, a standard awaiting status screen will be displayed.", "allOf": [{"$ref": "#/components/schemas/URL"}]}, "pending_redirect_delay": {"description": "How many seconds the customer spends on the standard awaiting status screen before being offered to go to `pending_redirect`. With `0`, the customer is redirected to `pending_redirect` immediately. Otherwise, once the delay passes, a button leading to `pending_redirect` is displayed; if the payment completes earlier, the customer is taken to `success_redirect`/`failure_redirect` as usual.\n\nA non-zero value requires `pending_redirect`.", "type": "integer", "minimum": 0, "maximum": 180, "default": 0}, "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."}, "source_platform": {"type": "string", "nullable": true, "readOnly": true, "description": "An identifier of an external platform that created this object."}, "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"}]}, "direct_post_url": {"description": "URL that can be used for Direct Post integration. \n\nThis functionality is activated for each merchant account individually. Please consult with your account manager if you wish to use it. \n\nWill be null if payment for purchase is not possible, `purchase.request_client_details` isn't empty or success_redirect/failure_redirect are not provided - these all break the usual direct post flow.\n\nTo leverage Direct Post checkout, create a `<form>` having `method=\"POST\" action=\"<direct_post_url value>\"` and include the following inputs:\n\n`cardholder_name: text, Latin letters only (space and apostrophe (`'`), dot (`.`), dash (`-`) symbols are also allowed), max 30 chars`\n\n---\n\n`card_number: text, digits only, no whitespace, max 19 chars`\n\n---\n\n`expires: text in 'MM/YY' format, digits and a slash only /^\\d{2}\\/\\d{2}$/, max 5 chars`\n\n---\n\n`cvc: numeric string of 3 or 4 digits`\n\n---\n\n`remember_card: checkbox with value=\"on\" (the default when omitting value attribute of a checkbox input)`\n\nEnsure the validation as listed above! Validation errors will be treated as payment failures. Obviously, you can style this form to fit in with the rest of your website.\n\nWhen your payer submits this form (don't forget a `<button>` or `<input type=\"submit\">`), he will POST the data directly to the gateway system. There, with minimal interaction with gateway's interface, payment will be processed. In the process, your customer might get redirected to authenticate against 3D Secure system of his card issuer bank (this depends on settings of his card and your account). After that, payer will be taken to `success_redirect` or `failure_redirect` depending on the payment result (as in the usual payment flow).\n\nBe aware, though, that while not having to process card data allows you not to comply with the entirety of PCI DSS SAQ D requirements, having sensitive cardholder data entry form on your website does raise your PCI DSS scope to SAQ A-EP. Contact your account manager to receive advisory and assistance for this integration method.", "readOnly": true, "nullable": 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: `az`, `de`, `en`, `en-GB`, `es`, `et`, `fr`, `it`, `lt`, `lv`, `pt`, `pt-BR`, `ru`, `tr`, `uk`.", "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\"."}, "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- direct_post: transaction executed via direct POST request\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- ledger: transaction intialized from Ledger integration\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- prestashop: transaction intialized from PrestaShop module\n- server_to_server: transaction executed via server to server API\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", "direct_post", "edd", "fluentcart", "fluentforms", "formidableforms", "givewp", "gohighlevel", "gravityforms", "hostbill", "import", "ledger", "link", "magento", "opencart", "payform", "paymattic", "perfexcrm", "prestashop", "server_to_server", "shopify", "web_office", "whmcs", "woocommerce", "woocommerce_subscriptions", "wpcharitable", "wpfunnels"]}, "TransactionProduct": {"type": "string", "description": "Product category the transaction belongs to.\n\n- bank_payment: bank_payment (Payment.payment_type == \"bank_payment\")\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- invoice: Purchase created as an invoice through the merchant portal (Purchase.product == \"billing_invoices\")\n- payout: Payout to a client's payment card\n- payout_balance_transfer: Transfer of funds between the acquirer and payout balances\n- purchase: Purchase created through the merchant API (Purchase.product == \"purchases\")\n- refund: refund (Payment.payment_type == \"refund\")\n- subscription: Purchase created using a subscription (Purchase.product is either \"billing_subscriptions\" or \"billing_subscriptions_invoice\")", "enum": ["bank_payment", "chargeback", "chargeback_reversal", "custom_payment", "invoice", "payout", "payout_balance_transfer", "purchase", "refund", "subscription"]}, "Turnover": {"type": "object", "description": "Company turnover statistics", "properties": {"turnover": {"allOf": [{"$ref": "#/components/schemas/MoneyAmount"}, {"description": "Amount transferred through a company"}]}, "fee_sell": {"$ref": "#/components/schemas/FeeSell"}, "count": {"type": "object", "description": "Transaction counts processed withing the selected filters", "properties": {"all": {"type": "integer", "description": "Number of transactions that contributed to the turnover. This can be used for calculating average `turnover` and `fee_sell` within the selected filters."}}}}, "example": {"turnover": 93408, "fee_sell": 1750, "count": {"all": 175}}}, "TurnoverPair": {"type": "object", "description": "Incoming and outgoing Company turnover statistics", "properties": {"incoming": {"$ref": "#/components/schemas/Turnover"}, "outgoing": {"$ref": "#/components/schemas/Turnover"}}}, "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"}}}}