Gaming Payments
Home
Solutions
ForexCasinosPayment Coverage
DevelopersAboutGET STARTED
Developers

Public REST API

OpenAPI 3.0.0Version v1
Base URL
https://gate.gamingpayments.com/api/v1
Authentication

Pass your secret API key as a bearer token in the Authorization header of every request:

Authorization: Bearer <secret key>

All the endpoints below have a prefix of https://gate.gamingpayments.com/api/v1/ (e.g. POST https://gate.gamingpayments.com/api/v1/purchases/).

You 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>.

Before starting the development, we recommend checking out the list of ready-to-go connectors to the popular platforms we’ve already built for you. It might save you some precious time if you use one of these to develop your project.

Plugins: WooCommerce, OpenCart, Magento, PrestaShop

Libraries: PHP, Java, C#, Node.js

SDKs: iOS, Android

Online Purchases

Prebuilt checkout (Redirect)

Redirect integration allows running payments using the prebuilt payment flow.

To 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).

*You have three options to check payment status:*

  1. Use success_callback parameter of the Purchase object.
  1. Use GET /purchases/<purchase_id>/ request.
  1. 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.

Setting 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.

This flag can also enable preauthorization capability, allowing you to save the card without a financial transaction, if possible.

If 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.

To 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.

Custom checkout — Client side (Direct Post)

Direct post integration allows running payments through the custom payment flow.

To accept payments in your application or website, use POST /purchases/ request to create a Purchase.

To 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.

You 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.

For more details, see the documentation on Purchase's direct_post_url field.

Tokenization & recurring payments

You can store card tokens and charge the respective cards without user interaction if the payment channel supports tokenization.

When 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.

To 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.

Use "recurring_token": "initial_purchase_id" in all the upcoming POST /purchases/{new_purchase_id}/charge/ requests.

If 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.

Custom checkout — Server side (Server-to-Server)

Server-to-Server ("S2S") integration allows running payments on the server level without direct interaction between the client’s browser or application and API.

You can build an integration that prevents payers from accessing platform resources directly. In this flow, 3D Secure implementation allows API clients to:

Check 3D Secure enrolment, and if the card is enrolled, receive ACS URL together with all the necessary params for redirection to ACS (PaReq, MD); Redirect the payer to the ACS system of their issuer bank; Receive the payer back and execute the authorization with a separate request.

If the card is not enrolled in 3D Secure, authorization will execute synchronously.

Please 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.

To accept payments in your application or website via S2S:

  1. Ensure the Purchase is created as described in Custom payment flow — 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);
  2. 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):

POST {direct_post_url}?s2s=true

Specify the following headers:

Content-Type: application/json Authorization: Bearer {S2S token}

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’s browser as it can affect 3D Secure success rate):

{ "cardholder_name": "John Doe", "card_number": "4444333322221111", "expires": "01/23", "cvc": "123", "remember_card": "on", "remote_ip": "8.8.8.8", "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36", "accept_header": "text/html", "language": "en-US", "java_enabled": false, "javascript_enabled": true, "color_depth": 24, "utc_offset": 0, "screen_width": 1920, "screen_height": 1080 }

|Field name&nbsp;|Required&nbsp;|Validation criteria/remarks&nbsp;|Default value| |--- |--- |---|--- | |cardholder_name|Y|Latin letters only (space and apostrophe ('), dot (.), dash (-) symbols are also allowed), max 45 characters|| |card_number|Y|text, digits only, no whitespace, max 19 characters|| |expires|Y|text in 'MM/YY' format, digits and a slash only (/^\\d{2}\\/\\d{2}$/), max 5 characters|| |cvc|Y|numeric string of 3 or 4 digits|| |remember_card|N|literal value "on" to save card, any other string otherwise|| |remote_ip|Y|external IP of payer’s browser in IPv4 or IPv6 format|| |user_agent|N|User-Agent as sent by the payer’s 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| |accept_header|N|Same as above, max 2048 characters|text/html| |language|N|Same as above, max 8 characters|en-US| |java_enabled|N|boolean|false| |javascript_enabled|N|boolean|true| |color_depth|N|integer in 0-255 range|24| |utc_offset|N|integer in -32,768 to 32,767 range|0| |screen_width|N|integer in uint64 range|1920| |screen_height|N|integer in uint64 range|1080|

  1. If the card is not enrolled in 3S Secure, then a response will contain the field "status" with one of the following values:

"executed" in case of a successful payment authorization; "authorized" in case fund reservation using Purchase.skip_capture was requested; "pending" in case the acquirer was not able to provide final status yet (in this case you need to await a Webhook callback); "error" in case of an authorization error.

Example:

{"status": "executed"}

You will receive "executed", "authorized" or "pending" statuses with a response status code 200 and "error" status - with a status code of 400.

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.

  1. 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:

{ "status": "3DS_required", "Method": "(POST|GET)", "PaReq": "...", "MD": "... (can arrive empty)", "URL": "http://url.of.acs.bank/", "callback_url": "https://..." }

It’s necessary to ensure your client’s 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 – in that case, you can send it further as an empty string.

In addition to those, you also need to include the `TermUrl` parameter in the client’s browser request, pointing to the URL in your system where the customer’s 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.

  1. Once the client is back to TermUrl in your system and you have received the MD and PaRes, it’s needed to transmit them to the platform to complete the authorization. Send the following request from your server code (no auth headers required):

POST {callback_url from step 4.}

Content-Type: application/x-www-form-urlencoded MD={MD received, if any}&PaRes={PaRes received}

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.

Testing Integration

It’s possible to test-drive all checkouts using a test Purchase.

For a successful payment, you can use the following card numbers:

  • 4444 3333 2222 1111 - non-3D Secure card
  • 5555 5555 5555 4444 - 3D Secure card

For both cards, please use:

  • any cardholder name
  • any expiry larger or equal to the current month/year
  • CVC = 123

For a failed payment, please change the CVC or expiration date.

When 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.

Billing

Invoicing

To 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.

To 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/.

If 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.

Subscriptions

Subscriptions 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.

If 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.

By default, the system generates invoices and processes subscription payments at the beginning of the billing cycle.

If 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.

The 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.

Callbacks

Two methods for defining asynchronous callbacks are supported - Purchase success callbacks and webhooks.

Purchase success callbacks

Purchase success callbacks are defined by providing a target URL in the success_callback field on Purchase creation (see POST /purchases/). The system will generate a callback when:

These 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) triggered the callback.

The 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.

Webhooks

For creating and modifying webhooks, see the Webhook CRUD API specification.

Webhook callback payloads are signed using a dedicated key pair. You can obtain the public key from Webhook.public_key. See the Authentication section below for more details.

Delivery protocol

When 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.

Please 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.

Callback 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.

Authentication

Payloads 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.

You can obtain the public key for Webhook authentication from Webhook.public_key of the corresponding Webhook.

You can obtain the public key for success callback authentication from GET /public_key/.

Please note the provider is not responsible for any financial losses incurred due to not implementing payload signature verification.

Purchases

post/purchases/

Create a purchase – the main request for any e-commerce integration.

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).

You 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.

Using skip_capture flag allows you to separate the authentication and payment execution steps, allowing you to reserve funds on payer’s card account for some time. This flag can also enable preauthorization capability, allowing you to save the card without a financial transaction, if available.

In 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.

Instead 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.

To 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.

Request bodyrequired

Body schema: Purchase

Example
{
  "client": {
    "email": "test@test.com"
  },
  "purchase": {
    "products": [
      {
        "name": "test",
        "price": 100
      }
    ]
  },
  "brand_id": "409eb80e-3782-4b1d-afa8-b779759266a5"
}
Responses
201OK→ Purchase
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
get/purchases/{id}/

Retrieve an object by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
200OK→ Purchase
404No such object
post/purchases/{id}/cancel/

Cancel a pending purchase.

If you have a Purchase that payment is possible for, using this request you can guarantee that it won't be paid.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
200OK→ Purchase
404No such object
post/purchases/{id}/release/

Release funds on hold.

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.

If 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.

If 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.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
200OK→ Purchase
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
404No such object
post/purchases/{id}/capture/

Capture a previously authorized payment.

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.

If 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.

If 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.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Request body
amount
integer

Amount to be captured. Used to perform partial captures. Remainder will be automatically released.

Responses
200OK→ Purchase
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
404No such object
post/purchases/{id}/charge/

Charge or Hold a purchase using a saved token.

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.

If 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.

If 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.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Request bodyrequired
recurring_token
stringuuid

ID of a recurring token (Purchase having is_recurring_token == true) to use.

Example
{
  "recurring_token": "ea582899-78ec-4c3a-9cb3-08f922e556b6"
}
Responses
200OK→ Purchase
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
404No such object
post/purchases/{id}/delete_recurring_token/

Delete a recurring token associated with a purchase.

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.

If 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.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
200OK→ Purchase
404No such object
post/purchases/{id}/refund/

Refund a paid purchase.

Will generate a Payment object and return it as a successful response.

Optional amount argument can be included in the request body to request a partial refund.

Consult refund_availability field on Purchase on details whether this Purchase can be refunded or not.

If 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.

If 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.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Request body
amount
integer

Amount to refund in minor units of the purchase's currency - e.g. 100 for €1.00. Should not be more than Purchase.refundable_amount.

Optional; if not provided, a full refund will be executed. See the description for Purchase.refund_availability field.

reference
string

Optional custom reference for the refund.

Example
{
  "amount": 120,
  "reference": "REFUND-123"
}
Responses
200OK→ Payment
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
404No such object
post/purchases/{id}/mark_as_paid/

Mark a purchase as paid.

Will set the purchase's status to paid. purchase.marked_as_paid field will also be set to true to distinguish this purchase.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Request body
paid_on
number

UTC timestamp at which this purchase was paid. Current time will be used if omitted.

Example
{
  "paid_on": 1635162311
}
Responses
200OK→ Purchase
404No such object
post/purchases/{id}/resend_invoice/

Re-sends invoice

Will re-send the invoice.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
200OK→ Purchase
404No such object

Payment methods

get/payment_methods/

Get the list of payment methods available for your purchase.

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.

In 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).

Please 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

Query parameters
brand_idrequired
string

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.

currencyrequired
string

Currency you'd use in your Purchase in ISO 4217 format, e.g. EUR.

country
string

Country code in the ISO 3166-1 alpha-2 format (e.g. GB). Optional.

recurring
boolean

If provided in the format of recurring=true, will filter out the methods that don't support recurring charges (see POST /purchases/{id}/charge/).

skip_capture
boolean

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).

preauthorization
boolean

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).

language
string

Language code in the ISO 639-1 format (e.g. 'en'). Optional.

Responses
200OK
{
  "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"
  ]
}
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}

Payout methods

get/payout_methods/

Get the list of payout methods available for your payout.

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.

In 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).

Please 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

Query parameters
brand_idrequired
string

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.

currencyrequired
string

Currency you'd use in your Payout in ISO 4217 format, e.g. EUR.

language
string

Language code in the ISO 639-1 format (e.g. 'en'). Optional.

Responses
200OK
{
  "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"
  ]
}
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}

Payouts

post/payouts/

Create an unprocessed payout object. A separate request is needed to execute the payout.

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:

expiry_month: string; 1-2 digits

expiry_year: string; 1-2 digits,

card_number: string; 16-19 chars,

cardholder_name: string; 1-30 chars. For wallet payouts, please contact support to get specific details on how to send a POST request to execution_url. 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.

For response to the second request having a code of 200, status = success means that payout was already executed.

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.

It's advised to subscribe to payout.failed and payout.success webhook events.

To 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.

Request bodyrequired

Body schema: Payout

Example
{
  "client": {
    "email": "test@example.com"
  },
  "payment": {
    "amount": 10000,
    "currency": "EUR",
    "description": "This is a description"
  },
  "brand_id": "f025d78f-3d23-49d1-a377-e2bf7e318a25"
}
Responses
201OK→ Payout
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
get/payouts/{id}/

Retrieve an object by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
200OK→ Payout
404No such object

Billing

post/billing/

Send an invoice to one or several clients.

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.

A 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/.

Note 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/.

Request bodyrequired
type
stringread-only

Object type identifier

id
stringuuidread-only
created_on
UnixTimestampread-only

Object creation time

updated_on
UnixTimestampread-only

Object last modification time

purchaserequired
PurchaseDetails
company_id
stringuuidread-only
number_of_billing_cycles
integer

Limits number of billing cycles for each client if set to a non-zero value

is_test
booleanread-only

Indicates this is a test object, created using test API keys or using Billing section of UI while in test mode.

user_id
stringuuidread-onlynullable

ID of user who has created this object in the Billing UI, if applicable.

brand_id
stringuuid

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
string
is_subscriptionrequired
boolean

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
Timestampnullable

Sets issued on the Purchase objects generated. Generated from current day in purchase.timezone if not provided. Read-only if is_subscription == true.

invoice_due
UnixTimestampnullable

Sets due on the Purchase objects generated. Required if is_subscription == false, read-only otherwise.

invoice_skip_capture
boolean

Sets skip_capture on the Purchase objects generated. false by default. Read-only if is_subscription == true.

default: false
invoice_send_receipt
boolean

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.

default: false
subscription_period
integer

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".

Variable 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.

Both 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.

default: 1
subscription_period_units
PeriodUnits

See subscription_period.

default: "months"
subscription_due_period
integer

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.

default: 7
subscription_due_period_units
PeriodUnits

See subscription_due_period.

default: "days"
subscription_charge_period_end
boolean

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.

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; read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if is_subscription == false.

default: false
subscription_trial_periods
integer

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.

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; read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if is_subscription == false.

default: 0
subscription_active
boolean

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.

Ignored (read-only) if is_subscription == false.

default: false
subscription_has_active_clients
booleanread-only

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.

While 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.

If this is true, you're only allowed to edit subscription_due_period, subscription_due_period_units and subscription_active.

Is always false if is_subscription == false.

force_recurring
boolean

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.

default: false
upsell_campaigns
string[]

Array of IDs of related Upsell campaigns.

referral_campaign_id
stringuuidnullable

ID of Referral campaign.

clientsrequired
BillingTemplateClient[]
Responses
200OK
[
  "720e2c96-ef94-4baa-90b6-d61ef6fd675a"
]
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
get/billing_templates/

List all billing templates.

Responses
200OK
post/billing_templates/

Create a template to issue repeated invoices from in the future, with or without a subscription.

BillingTemplate generates Purchase objects, either to issue one-time invoices or in a subscription.

It 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.

If 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.

If 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.

Request bodyrequired

Body schema: BillingTemplate

Responses
201OK→ BillingTemplate
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
get/billing_templates/{id}/

Retrieve a billing template by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
200OK→ BillingTemplate
404No such object
put/billing_templates/{id}/

Update a billing template by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Request bodyrequired

Body schema: BillingTemplate

Responses
200OK→ BillingTemplate
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
404No such object
delete/billing_templates/{id}/

Delete a billing template by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
204OK
post/billing_templates/{id}/send_invoice/

Send an invoice, generating a purchase from billing template data.

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.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Request bodyrequired

Body schema: BillingTemplateClient

Example
{
  "client_id": "b79d3df6-2f69-4426-acee-eda049d83e18"
}
Responses
200OK→ Purchase
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
post/billing_templates/{id}/add_subscriber/

Add a billing template client and activate recurring billing (is_subscription: true).

Use this request with a BillingTemplate having is_subscription == true. Two scenarios are possible:

• 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.

• 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/).

Path parameters
idrequired
string · uuid

Object ID (UUID)

Request bodyrequired

Body schema: BillingTemplateClient

Example
{
  "client_id": "b79d3df6-2f69-4426-acee-eda049d83e18"
}
Responses
200OK
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
get/billing_templates/{id}/clients/

List all billing template clients for this billing template.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
200OK
get/billing_templates/{id}/clients/{id}/

Retrieve a billing template client by client's ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

idrequired
string · uuid

Object ID (UUID)

Responses
200OK→ BillingTemplateClient
404No such object
patch/billing_templates/{id}/clients/{id}/

Partially update a billing template client by client's ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

idrequired
string · uuid

Object ID (UUID)

Request bodyrequired

Body schema: BillingTemplateClient

Example
{
  "status": "active"
}
Responses
200OK→ BillingTemplateClient
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
404No such object

Clients

get/clients/

List all clients.

Responses
200OK
post/clients/

Create a new client.

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.

Each BillingTemplateClient (there can be many attached to a single BillingTemplate) will bind a single Client to a BillingTemplate.

Request bodyrequired

Body schema: Client

Responses
201OK→ Client
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
get/clients/{id}/

Retrieve an object by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
200OK→ Client
404No such object
put/clients/{id}/

Update a client by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Request bodyrequired

Body schema: Client

Responses
200OK→ Client
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
404No such object
patch/clients/{id}/

Partially update a client by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Request bodyrequired

Body schema: Client

Responses
200OK→ Client
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
404No such object
delete/clients/{id}/

Delete a client by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
204OK
get/clients/{id}/recurring_tokens/

List recurring tokens saved for a client.

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.

You 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.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
200OK
get/clients/{id}/recurring_tokens/{id}/

Retrieve an object by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
200OK→ ClientRecurringToken
404No such object
delete/clients/{id}/recurring_tokens/{id}/

Delete a client recurring token by ID.

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.

You 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).

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
204OK

Webhooks

get/webhooks/

List all webhooks.

Responses
200OK
post/webhooks/

Create a new webhook.

Request bodyrequired

Body schema: Webhook

Responses
201OK→ Webhook
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
get/webhooks/{id}/

Retrieve an object by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
200OK→ Webhook
404No such object
put/webhooks/{id}/

Update a webhook by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Request bodyrequired

Body schema: Webhook

Responses
200OK→ Webhook
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
404No such object
patch/webhooks/{id}/

Partially update a webhook by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Request bodyrequired

Body schema: Webhook

Responses
200OK→ Webhook
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
404No such object
delete/webhooks/{id}/

Delete a webhook by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
204OK
get/webhooks/deliveries/

List webhook deliveries for a specific object.

Returns a paginated list of webhook deliveries for a specific source object (Purchase, Payment, Payout, or BillingTemplateClient).

You must provide both id and source_type query parameters to identify the object whose webhook deliveries you want to retrieve.

Deliveries show the complete history of webhook attempts for the specified object, including successful deliveries, failures, and retries.

Query parameters
idrequired
string · uuid

ID of the source object (Purchase, Payment, Payout, or BillingTemplateClient) to retrieve webhook deliveries for.

source_typerequired
WebhookSourceType

Type of the source object.

Responses
200OK
{
  "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"
      }
    }
  ]
}
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
404No such object

Public Key

get/public_key/

Get a callback public key.

Returns public key for authenticating company callback payloads

Responses
200Public key for authenticating callback payloads→ PublicKey

Account

get/account/json/balance/

Get company balance.

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.

Query parameters
tokenized
boolean

Filter result set by whether the transaction was performed using a recurring execution token

from
integer

Retrieve a past balance value at a specific Unix timestamp

brand
string · uuid

Filter result set to only include the specified brand UUID(s)

terminal_uid
string · uuid

Filter result set to only include the specified terminal UUID(s)

currency
string

Filter result set to only include specified currency(ies)

payment_method
PaymentMethod

Filter result set to only include specified payment methods(s). See PaymentMethod fro more information.

product
TransactionProduct

Filter result set to only include specified products(s). See TransactionProduct fro more information.

flow
TransactionFlow

Filter result set to only include specified transaction creation or execution flow(s). See TransactionFlow fro more information.

country
string · ISO 3166-1 alpha-2

Filter result set to only include specified client country(ies) in ISO 3166-1 alpha-2 format

Responses
200Company balance successfully retrieved→ BalanceByCurrency
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
get/account/json/turnover/

Get company turnover.

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.

Query parameters
tokenized
boolean

Filter result set by whether the transaction was performed using a recurring execution token

from
integer

Filter result set to only include values older or equal to the provided Unix timestamp

to
integer

Filter result set to only include values younger than the provided Unix timestamp

brand
string · uuid

Filter result set to only include the specified brand UUID(s)

terminal_uid
string · uuid

Filter result set to only include the specified terminal UUID(s)

currency
string

Filter result set to only include specified currency(ies)

payment_method
PaymentMethod

Filter result set to only include specified payment methods(s). See PaymentMethod fro more information.

product
TransactionProduct

Filter result set to only include specified products(s). See TransactionProduct fro more information.

flow
TransactionFlow

Filter result set to only include specified transaction creation or execution flow(s). See TransactionFlow fro more information.

country
string · ISO 3166-1 alpha-2

Filter result set to only include specified client country(ies) in ISO 3166-1 alpha-2 format

Responses
200Company turnover successfully retrieved→ TurnoverPair
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}

Balance

get/balance/

Get balance data.

Returns balance data, including ecommerce and bank accounts.

Responses
200Balance data successfully retrieved→ CompanyBalance
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}

Company Statements

get/company_statements/

List all generated statements.

Responses
200OK
post/company_statements/

Schedule a statement generation.

With this request, you can schedule a statement generation for a company.

In a response, you will get an object with the following structure. Main fields to look out for here are id, status and download_url.

Query parameters
from
integer

Filter result set to only include values older or equal to the provided Unix timestamp

to
integer

Filter result set to only include values younger than the provided Unix timestamp

paid_from
integer

Filter paid result set to only include values older or equal to the provided Unix timestamp

paid_to
integer

Filter paid result set to only include values younger than the provided Unix timestamp

updated_from
integer

Filter result set to only include values older or equal to the provided last modification time Unix timestamp

updated_to
integer

Filter result set to only include values younger than the provided last modification time Unix timestamp

brand_id
string · uuid

Filter result set to only include the specified brand UUID(s)

shop_id
string · uuid

Filter result set to only include the specified shop UUID(s)

q
string · string

Filter result set to only include results including a specified text (search over a ton of text fields)

products
string · string

Filter result set to only include results including a specified text in products

total
string · float

Filter result set to only include results with a total between min and max value. Must include 2 values, if any - (min, max).

currency
string

Filter result set to only include specified currency(ies)

payment_method
PaymentMethod

Filter result set to only include specified payment methods(s). See PaymentMethod fro more information.

three_d_secure
string · bool

Filter result set to only include results with a 3-D verification.

country
string · ISO 3166-1 alpha-2

Filter result set to only include specified client country(ies) in ISO 3166-1 alpha-2 format

status
string · string

Filter result set to only include results with a specific status. See Purchase and Payout for more information.

product
TransactionProduct

Filter result set to only include specified products(s). See TransactionProduct fro more information.

Request bodyrequired

Body schema: CompanyStatement

Example
{
  "format": "csv",
  "timezone": "UTC"
}
Responses
201OK→ CompanyStatement
400Invalid data submitted or request processing error
{
  "__all__": {
    "message": "descriptive error message",
    "code": "error_code"
  }
}
get/company_statements/{id}/

Retrieve a statement by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
200OK→ CompanyStatement
404No such object
post/company_statements/{id}/cancel/

Cancel a statement generation by ID.

Path parameters
idrequired
string · uuid

Object ID (UUID)

Responses
200OK→ CompanyStatement
404No such object

Schemas

Balance

Company Balance in a specific currency

gross_balance
MoneyAmount

Raw Company balance without any fees or reserved amounts subtracted

balance
MoneyAmount

Company gross balance with transaction fees subtracted

available_balance
MoneyAmount

Company balance currently available for withdrawal

reserved
MoneyAmount

Amount protected from withdrawal for an amount of time as per the brand configuration

pending_outgoing
MoneyAmount

Amount currently pending withdrawal

fee_sell
FeeSell

BalanceByCurrency

Map of currency to company Balance for the specific currency

BankAccount

Bank account

id
object

Bank account ID

iban
string

International Bank Account Number (IBAN)

swift
string

Society for Worldwide Interbank Financial Telecommunication (SWIFT) code

bank_account
string

Bank account number

bank_code
string

Bank code

real_bank_account
string

Real bank account number

real_bank_code
string

Real bank code

currency
Currency

Currency code

status
string

Bank account status

name
string

Bank account name

reference
string

Bank account reference

available_balance
MoneyAmount

Available balance

reserved_balance
MoneyAmount

Reserved balance

extended_ui
string

Extended UI

fx_currencies
Currency[]

Foreign exchange currencies

BankAccountMixin

bank_account
string

Bank account number (e.g. IBAN)

bank_code
string

SWIFT/BIC code of the bank

BaseModel

type
stringread-only

Object type identifier

id
stringuuidread-only
created_on
UnixTimestampread-only

Object creation time

updated_on
UnixTimestampread-only

Object last modification time

BillingTemplate

BillingTemplate generates Purchase objects, either to issue one-time invoices or in a subscription.

It 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.

If 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.

If 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.

type
stringread-only

Object type identifier

id
stringuuidread-only
created_on
UnixTimestampread-only

Object creation time

updated_on
UnixTimestampread-only

Object last modification time

purchaserequired
PurchaseDetails
company_id
stringuuidread-only
number_of_billing_cycles
integer

Limits number of billing cycles for each client if set to a non-zero value

is_test
booleanread-only

Indicates this is a test object, created using test API keys or using Billing section of UI while in test mode.

user_id
stringuuidread-onlynullable

ID of user who has created this object in the Billing UI, if applicable.

brand_id
stringuuid

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
string
is_subscriptionrequired
boolean

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
Timestampnullable

Sets issued on the Purchase objects generated. Generated from current day in purchase.timezone if not provided. Read-only if is_subscription == true.

invoice_due
UnixTimestampnullable

Sets due on the Purchase objects generated. Required if is_subscription == false, read-only otherwise.

invoice_skip_capture
boolean

Sets skip_capture on the Purchase objects generated. false by default. Read-only if is_subscription == true.

default: false
invoice_send_receipt
boolean

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.

default: false
subscription_period
integer

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".

Variable 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.

Both 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.

default: 1
subscription_period_units
PeriodUnits

See subscription_period.

default: "months"
subscription_due_period
integer

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.

default: 7
subscription_due_period_units
PeriodUnits

See subscription_due_period.

default: "days"
subscription_charge_period_end
boolean

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.

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; read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if is_subscription == false.

default: false
subscription_trial_periods
integer

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.

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; read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if is_subscription == false.

default: 0
subscription_active
boolean

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.

Ignored (read-only) if is_subscription == false.

default: false
subscription_has_active_clients
booleanread-only

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.

While 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.

If this is true, you're only allowed to edit subscription_due_period, subscription_due_period_units and subscription_active.

Is always false if is_subscription == false.

force_recurring
boolean

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.

default: false
upsell_campaigns
string[]

Array of IDs of related Upsell campaigns.

referral_campaign_id
stringuuidnullable

ID of Referral campaign.

BillingTemplateClient

Connects a Client object to a BillingTemplate having is_subscription = true to store information about a single subscriber.

You will be able to pause an individual subscription client's cycle by PATCH-ing its' status field to the value of subscription_paused.

type
stringread-only

Object type identifier

id
stringuuidread-only
created_on
UnixTimestampread-only

Object creation time

updated_on
UnixTimestampread-only

Object last modification time

client_idrequired
stringuuid

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
integerread-only

Only used together with number_of_billing_cycles on BillingTemplate. Shows number of billing cycles passed when number of cycles is limited

invoice_reference
stringnullable

When present overrides reference for invoices generated for this client

status
enum

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.

Read-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.

pendinginactiveactivesubscription_paused
default: "inactive"
subscription_billing_scheduled_on
Timestampread-onlynullable

If not null, reports the date when the next billing is scheduled for this client.

payment_method_whitelist
string[]

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).

send_invoice_on_charge_failure
boolean

Sends invoice when subscription charge fails if this is true

default: true
send_invoice_on_add_subscriber
boolean

Sends invoice when POST /billing_templates/{id}/add_subscriber/ is called if this is true

default: false
send_receipt
boolean

Sends receipt when subscription charge succeeds if this is true

default: true

City

City name

Client

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.

Each BillingTemplateClient (there can be many attached to a single BillingTemplate) will bind a single Client to a BillingTemplate.

bank_account
string

Bank account number (e.g. IBAN)

bank_code
string

SWIFT/BIC code of the bank

emailrequired
Email
phone
Phone
full_name
string

Name and surname of client

personal_code
string

Personal identification code of client.

street_address
StreetAddress
country
Country
city
City
zip_code
ZIPCode
state
State
shipping_street_address
StreetAddress
shipping_country
Country
shipping_city
City
shipping_zip_code
ZIPCode
shipping_state
State
cc
Email[]

Email addresses to receive a carbon copy of all notification emails

bcc
Email[]

Email addresses to receive a blind carbon copy of all notification emails

legal_name
string

Legal name of company

brand_name
string

Company brand name

registration_number
string

Registration number of company

tax_number
string

Tax payer registration number

delivery_methods
object[]

List of delivery methods for invoices

default: [{"method":"email","options":{}}]
type
stringread-only

Object type identifier

id
stringuuidread-only
created_on
UnixTimestampread-only

Object creation time

updated_on
UnixTimestampread-only

Object last modification time

ClientDetails

Contains details about the client of a purchase or payment - the remote payer/fund recipient party.

bank_account
string

Bank account number (e.g. IBAN)

bank_code
string

SWIFT/BIC code of the bank

emailrequired
Email
phone
Phone
full_name
string

Name and surname of client

personal_code
string

Personal identification code of client.

street_address
StreetAddress
country
Country
city
City
zip_code
ZIPCode
state
State
shipping_street_address
StreetAddress
shipping_country
Country
shipping_city
City
shipping_zip_code
ZIPCode
shipping_state
State
cc
Email[]

Email addresses to receive a carbon copy of all notification emails

bcc
Email[]

Email addresses to receive a blind carbon copy of all notification emails

legal_name
string

Legal name of company

brand_name
string

Company brand name

registration_number
string

Registration number of company

tax_number
string

Tax payer registration number

delivery_methods
object[]

List of delivery methods for invoices

default: [{"method":"email","options":{}}]

ClientRecurringToken

payment_method
stringread-only

Payment method used to create this token, e.g. card.

description
stringread-only

Description of this token, if available. For card payments, this field will contain the masked card number.

type
stringread-only

Object type identifier

id
stringuuidread-only
created_on
UnixTimestampread-only

Object creation time

updated_on
UnixTimestampread-only

Object last modification time

CompanyBalance

Balance data

ecommerce
EcommerceItem[]

Ecommerce data

bank_accounts
BankAccount[]

Bank account data

payout_balances_enabled
object

CompanyStatement

format
string

Statement format, available formats: csv, xlsx.

timezone
stringTZ database name

Timezone to localize statement-specific timestamps

is_test
booleanread-only

Indicates this is a test object, created using test API keys or using Billing section of UI while in test mode.

company_uid
stringuuidread-only

ID of the Company.

query_string
stringread-only

Query parameters used to generate statement.

status
stringread-only

Status of statement generation e.g. pending, processing, success.

download_url
stringread-only

Download URL of a statement.

began_on
UnixTimestampread-only

Date and time for the beginning of statement generation process.

finished_on
UnixTimestampread-only

Date and time for finishing the statement generation process.

created_on
UnixTimestampread-only

Object creation time

updated_on
UnixTimestampread-only

Object last modification time

type
stringread-only

Statement request type

id
stringuuidread-only

ID of a statement

Country

Country code in the ISO 3166-1 alpha-2 format (e.g. 'GB')

Currency

Currency code in the ISO 4217 standard (e.g. 'EUR'). Default currency is EUR.

EcommerceItem

Ecommerce item

currency
Currency
gross_balance
MoneyAmount
balance
MoneyAmount
available_balance
MoneyAmount
reserved
MoneyAmount
pending_outgoing
MoneyAmount
fee_sell
MoneyAmount
payout_gross_balance
MoneyAmount
payout_balance
MoneyAmount
available_payout_balance
MoneyAmount
pending_payouts
MoneyAmount
payout_overdraft
MoneyAmount
payout_fee_sell
MoneyAmount

Email

Email address

Event

Available event types and when they are emitted:

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.

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.

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.

purchase.refund_failure: Emitted when a pending refund fails.

purchase.capture_failure:Emitted when a pending capture fails. The Purchase status is expected to be 'hold' after that.

purchase.release_failure: Emitted when a pending release fails. The Purchase status is expected to be 'hold' after that.

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.

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.

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.

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.

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.

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.

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.

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.

purchase.preauthorized: Emitted when preauthorization scenario (see description for the Purchase.skip_capture field) is executed successfully. Purchase will have a status of preauthorized.

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.

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.

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.

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.

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.

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.

payout.pending: Emitted when Payout execution has been initiated and is currently processing.

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.

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.

payment.charged_back: Emitted when a Payment is charged_back.

purchase.viewed: Emitted when a Purchase is viewed.

purchase.settled: Emitted when a Purchase is settled.

payout.created: Emitted when a Payout is created.

payment.chargeback_reversed: Emitted when a Payment chargeback is reversed.

FeeSell

IssuerDetails

Read-only details of issuer company/brand, persisted for invoice display.

website
URLread-only

Company website URL

legal_street_address
StreetAddressread-only
legal_country
Countryread-only
legal_city
Cityread-only
legal_zip_code
ZIPCoderead-only
bank_accounts
BankAccountMixin[]read-only
legal_name
stringread-only

Legal name of company

brand_name
stringread-only

Company brand name

registration_number
stringread-only

Registration number of company

tax_number
stringread-only

Tax payer registration number

MoneyAmount

Amount of money as the smallest indivisible units of the currency. Examples: 1 cent for EUR and 1 Yen for JPY.

Payment

A record of a performed financial transaction. Can be generated e.g. as a result of refund operation.

type
stringread-only

Object type identifier

id
stringuuidread-only
created_on
UnixTimestampread-only

Object creation time

updated_on
UnixTimestampread-only

Object last modification time

client
ClientDetailsread-only
payment
PaymentDetailsread-only
transaction_data
objectread-onlynullable

Payment method-specific, read-only, internal transaction data. Will contain information about all the transaction attempts, if available.

related_to
objectread-onlynullable

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>.

reference_generated
stringread-only

If an explicit invoice reference wasn't provided, this autogenerated value will be used as a reference instead.

reference
stringread-only

Invoice reference.

account_id
stringuuidread-only

ID of an account this Payment is associated with.

company_id
stringuuidread-only
is_test
booleanread-only

Indicates this is a test object, created using test API keys or using Billing section of UI while in test mode.

user_id
stringuuidread-onlynullable

ID of user who has created this object in the Billing UI, if applicable.

brand_id
stringuuidread-only

ID of the brand this Payment is associated with.

PaymentDetails

Details of an executed transaction. Read-only for Purchases and Payouts. For an unpaid Purchase, this object will be null.

is_outgoing
boolean

Denotes the direction of payment, e.g. for a paid Purchase, is granted to be false, true for payouts.

default: false
payment_type
enumread-only
purchasepurchase_chargepayoutbank_paymentrefundcustom
amount
MoneyAmount
currency
Currency
net_amount
MoneyAmountread-only
fee_amount
MoneyAmountread-only
pending_amount
MoneyAmountread-only
pending_unfreeze_on
UnixTimestampread-onlynullable
description
string
paid_on
UnixTimestampread-only

When the payment was accepted in (is_outgoing == false) or sent from (is_outgoing == true) the gateway system.

remote_paid_on
UnixTimestampread-only

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).

PaymentMethod

Payment method used to execute the transaction.

  • airtel: Airtel
  • american_express: American Express payment card
  • aronhub_redirect: Aronhub Redirect
  • beyounger_redirect: Beyounger Redirect
  • open_banking_a: Open Banking A
  • cybersource_hosted_checkout: Cybersource Hosted Checkout
  • discover: Discover payment card
  • ipsl_pgw: Ipsl Pgw
  • jcb: JCB payment card
  • jp_lapa: Jp Lapa
  • lapa_apgp: Apple/Google pay
  • lapa_redirect: Lapa Redirect
  • maestro: Maestro payment card
  • mastercard: Mastercard payment card
  • mtnmomo: Mtnmomo
  • paytota_airtel: Paytota Airtel
  • paytota_mtnmomo: Paytota Mtnmomo
  • pne_apm_ap: Pne Apm Ap
  • pne_apm_gp: Pne Apm Gp
  • pne_apm_redirect: Pne Apm Redirect
  • safaricom: Safaricom
  • spago_redirect: Spago
  • unionpay: UnionPay payment card
  • unknown: Payment method could not be determinded
  • visa: Visa payment card

Payout

Record of a single payout operation. Has a status attribute, e.g. can be initialized, error or success.

type
stringread-only

Object type identifier

id
stringuuidread-only
created_on
UnixTimestampread-only

Object creation time

updated_on
UnixTimestampread-only

Object last modification time

paymentrequired
PaymentDetails
clientrequired
ClientDetails
transaction_data
objectread-only

Payment method-specific, read-only transaction data. Will contain information about all the transaction attempts and possible errors, if available.

reference_generated
stringread-only

If you don't provide an invoice reference yourself, this autogenerated value will be used as a reference instead.

reference
string

Payout reference.

status
PayoutStatus
status_history
object[]read-only

History of status changes, latest last.

sender_name
string

Name of payout sender.

recipient_card_country
stringread-only

Recipient's card's registration country. Country code in the ISO 3166-1 alpha-2 format (e.g. GB).

recipient_card_brand
stringread-only

Recipient's card's brand, e.g. visa or mastercard.

payout_method_whitelist
string[]

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.

execution_url
stringread-only

URL that must be used for payout execution. See details in description.

brand_idrequired
stringuuid

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
objectread-only
company_id
stringuuidread-only
is_test
booleanread-only

Indicates this is a test object, created using test API keys or using Billing section of UI while in test mode.

user_id
stringuuidread-onlynullable

ID of user who has created this object in the Billing UI, if applicable.

PayoutStatus

Payout status. Can have the following values:

initialized: Payout was created, but not executed. Initial status to new Payouts.

pending: Payout's execution is currently pending

error: An error has occurred during the execution. Execution can be attempted again.

success: Payout was executed successfully.

PeriodUnits

Phone

Phone number in the <country_code> <number> format

Product

namerequired
string

Product name

quantity
stringfloat

Quantity of these products in invoice

default: 1
pricerequired
MoneyAmount

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.

discount
MoneyAmount

Total discount per this product in invoice

default: 0
tax_percent
stringfloat

Percent of tax added to the price of this product

default: 0
category
string

Product category

total_price_override
MoneyAmountnullable

PublicKey

PEM-encoded RSA public key for authenticating webhook or callback payloads

Purchase

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.

type
stringread-only

Object type identifier

id
stringuuidread-only
created_on
UnixTimestampread-only

Object creation time

updated_on
UnixTimestampread-only

Object last modification time

clientrequired
ClientDetails

Either this or .client_id is required.

purchaserequired
PurchaseDetails
payment
PaymentDetailsread-onlynullable
issuer_details
IssuerDetailsread-only
transaction_data
objectread-only

Payment method-specific, read-only transaction data. Will contain information about all the transaction attempts and possible errors, if available.

status
PurchaseStatus
status_history
object[]read-only

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.

viewed_on
UnixTimestampread-onlynullable

Time the payment form or invoice page was first viewed on

company_id
stringuuidread-only
is_test
booleanread-only

Indicates this is a test object, created using test API keys or using Billing section of UI while in test mode.

user_id
stringuuidread-onlynullable

ID of user who has created this object in the Billing UI, if applicable.

brand_idrequired
stringuuid

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
stringuuidread-onlynullable

ID of a BillingTemplate that has spawned this Purchase, if any.

client_id
stringuuidnullable

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.

If 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
boolean

Whether to send receipt email for this Purchase when it's paid.

default: false
is_recurring_token
booleanread-only

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
stringuuidread-onlynullable

ID of a recurring token (Purchase having is_recurring_token == true) that was used to pay this Purchase, if any.

skip_capture
boolean

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.

You 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.

Trying 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.

default: false
force_recurring
boolean

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.

default: false
reference_generated
stringread-only

If you don't provide an invoice reference yourself, this autogenerated value will be used as a reference instead.

reference
string

Invoice reference.

issued
Timestampnullable

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.

due
UnixTimestampnullable

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.

refund_availability
enumread-only

Specifies, if the purchase can be refunded fully and partially, only fully, partially or not at all.

allfull_onlypartial_onlypis_allpis_partialnone
refundable_amount
MoneyAmountread-only
currency_conversion
objectread-onlynullable

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.

payment_method_whitelist
string[]

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.

Using 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.

success_redirect
URL

When Purchase is paid for successfully, your customer will be taken to this link. Otherwise a standard screen will be displayed.

failure_redirect
URL

If there's a payment failure for this Purchase, your customer will be taken to this link. Otherwise a standard screen will be displayed.

cancel_redirect
URL

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: <>'" .

Be 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.

success_callback
URL

When Purchase is paid for successfully, the success_callback URL will receive a POST request with the Purchase object's data in body.

creator_agent
string

Identification of software (e.g. an ecommerce module and version) used to create this purchase, if any.

platform
enum

Platform this Purchase was created on.

webapiiosandroidmacoswindows
product
enumread-only

Defines which gateway product was used to create this Purchase.

purchasesbilling_invoicesbilling_subscriptionsbilling_subscriptions_invoice
created_from_ip
stringIPread-only

IP the Purchase was created from.

invoice_url
URLread-onlynullable

URL you will be able to access invoice for this Purchase at, if applicable

checkout_url
URLread-only

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.

You 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.

direct_post_url
URLread-onlynullable

URL that can be used for Direct Post integration.

This functionality is activated for each merchant account individually. Please consult with your account manager if you wish to use it.

Will 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.

To leverage Direct Post checkout, create a <form> having method="POST" action="<direct_post_url value>" and include the following inputs:

cardholder_name: text, Latin letters only (space and apostrophe ('), dot (.), dash (-) symbols are also allowed), max 30 chars

card_number: text, digits only, no whitespace, max 19 chars

expires: text in 'MM/YY' format, digits and a slash only /^\d{2}\/\d{2}$/, max 5 chars

cvc: numeric string of 3 or 4 digits

remember_card: checkbox with value="on" (the default when omitting value attribute of a checkbox input)

Ensure 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.

When 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).

Be 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.

marked_as_paid
booleanread-only

True if a purchase was manually marked as paid.

order_id
stringread-only

ID of corresponding order.

upsell_campaigns
string[]

Array of IDs of related Upsell campaigns.

referral_campaign_id
stringuuidnullable

ID of Referral campaign.

referral_code
stringread-only

Referral code used with purchase.

referral_code_generated
stringread-only

Referral code created by purchase.

referral_code_details
objectread-only

Referral code detailed information for purchase.

retain_level_details
objectread-only

Retain level detailed information for purchase.

PurchaseDetails

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).

currency
Currency
productsrequired
Product[]

Line items of the invoice. In case of a transaction with no invoice sent, specify a single Product forming the cost of transaction.

total
MoneyAmountread-only
language
stringISO 639-1

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
string
debt
MoneyAmount
default: 0
subtotal_override
MoneyAmountnullable
total_tax_override
MoneyAmountnullable
total_discount_override
MoneyAmountnullable
total_override
MoneyAmountnullable
request_client_details
string[]

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: []
timezone
stringTZ database name

Timezone to localize invoice-specific timestamps in, e.g. to display a concrete date for a due timestamp on the invoice.

due_strict
boolean

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.

default: false
email_message
stringread-only

An optional message to display to your customer in invoice email, e.g. "Your invoice for June".

metadata
object

Custom information with maximum length of 10000 characters

single_attempt
boolean

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.

default: false

PurchaseStatus

Purchase status. Can have the following values:

created: Purchase was created using POST /purchases/ or Billing API capabilities.

sent: Invoice for this purchase was sent over email using Billing API capabilities.

viewed: The client has viewed the payform and/or invoice details for this purchase.

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.

cancelled: Purchase was cancelled using the POST /purchases/{id}/cancel/ endpoint; payment for it is not possible anymore.

overdue: Purchase is past its' .due, but payment for it is still possible (unless e.g. POST /purchases/{id}/cancel/ is used).

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’s 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.

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.

released: This Purchase previously had hold status, but funds have since been released and returned to the customer's card.

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.

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.

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.

paid: Purchase was successfully paid for.

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.

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.

retrieved: A retrieval request was registered for this, previously paid, Purchase.

charged_back: A chargeback was registered for this, previously paid, Purchase.

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.

refunded: This Purchase had its payment refunded, fully or partially.

State

State code

StreetAddress

Street house number and flat address where applicable

Timestamp

TransactionFlow

Flow or pathway used to initiate or execute a transaction.

  • api: transaction initiated via the merchant API
  • direct_post: transaction executed via direct POST request
  • edd: transaction intialized from Easy Digital Downloads module
  • fluentcart: transaction intialized from FluentCart integration
  • fluentforms: transaction intialized from Fluentforms integration
  • formidableforms: transaction intialized from Formidableforms integration
  • givewp: transaction intialized from GiveWP integration
  • gohighlevel: transaction intialized from GoHighLevel integration
  • gravityforms: transaction intialized from Gravity Forms integration
  • hostbill: transaction intialized from Hostbill integration
  • import: transaction imported from external system
  • link: transaction initiated via shared link
  • magento: transaction intialized from Magento module
  • opencart: transaction intialized from OpenCart module
  • payform: transaction executed via the gateway payform
  • paymattic: transaction intialized from Paymattic integration
  • perfexcrm: transaction intialized from Perfex CRM
  • prestashop: transaction intialized from PrestaShop module
  • server_to_server: transaction executed via server to server API
  • shopify: transaction intialized from Shopify integration
  • web_office: transaction initiated via the merchant portal
  • whmcs: transaction intialized from WHMCS integration
  • woocommerce: transaction intialized from Woocommerce module
  • woocommerce_subscriptions: transaction intialized from Woocommerce subscriptions module
  • wpcharitable: transaction intialized from WPCharitable integration
  • wpfunnels: transaction intialized from WPFunnels Pro module

TransactionProduct

Product category the transaction belongs to.

  • bank_payment: bank_payment (Payment.payment_type == "bank_payment")
  • chargeback: Purchase chargeback created through the merchant API (Purchase.product == "chargeback")
  • chargeback_reversal: Purchase chargeback reversal created through the Wizard UI
  • custom_payment: custom_payment (Payment.payment_type == "custom_payment")
  • invoice: Purchase created as an invoice through the merchant portal (Purchase.product == "billing_invoices")
  • payout: Payout to a client's payment card
  • payout_balance_transfer: Transfer of funds between the acquirer and payout balances
  • purchase: Purchase created through the merchant API (Purchase.product == "purchases")
  • refund: refund (Payment.payment_type == "refund")
  • subscription: Purchase created using a subscription (Purchase.product is either "billing_subscriptions" or "billing_subscriptions_invoice")

Turnover

Company turnover statistics

turnover
MoneyAmount

Amount transferred through a company

fee_sell
FeeSell
count
object

Transaction counts processed withing the selected filters

TurnoverPair

Incoming and outgoing Company turnover statistics

incoming
Turnover
outgoing
Turnover

URL

UnixTimestamp

Webhook

titlerequired
string

Arbitrary title of webhook

all_events
boolean

Specifies this webhook should trigger on all event types. Either this or events is required.

default: false
public_key
PublicKey
eventsrequired
Event[]

List of events to trigger webhook callbacks for. Either this or all_events is required.

callbackrequired
URL
type
stringread-only

Object type identifier

id
stringuuidread-only
created_on
UnixTimestampread-only

Object creation time

updated_on
UnixTimestampread-only

Object last modification time

WebhookDelivery

Record of a webhook delivery attempt, including the event data sent, delivery status, and retry attempts.

created_on
stringdate-time

Timestamp when the webhook delivery was created.

delivered_on
stringdate-timenullable

Timestamp when the webhook was successfully delivered. Null if not yet delivered or failed.

attempts
integer

Number of delivery attempts made for this webhook.

delivery_attempts
WebhookDeliveryAttempt[]

List of delivery attempts made for this webhook, ordered by most recent first.

url
stringurl

The URL the webhook is being (or was) delivered to.

event
Event

The event type that triggered this delivery.

payload
objectnullable

The actual payload that was sent (or will be sent) to the webhook endpoint. Contains the full object data for the event.

WebhookDeliveryAttempt

Record of an individual webhook delivery attempt.

attempted_on
stringdate-time

Timestamp when this delivery attempt was made.

error_message
string

Error message if the delivery attempt failed, describing what went wrong.

WebhookSourceType

Type of object that can trigger webhook events.

ZIPCode

ZIP or postal code