# Smart Glocal API (Full) > Auto-generated full documentation content from llms.txt links ## Dashboard > Source: /docs/dashboard Smart Glocal Dashboard is a tool that allows you to track all transactions—payments, payouts, and refunds—across your Smart Glocal integrations. ## Core features In the Dashboard, you can: * view the [list of transactions](#registry) * find transactions using the [date filter or AI search](#searching) * download transaction reports in CSV format ### Transaction list Click any row in the list to open a panel with the details of a specific transaction. The details include the following data: * **Session ID** * **Transaction ID** * **Type**: payment, payout, refund * **Method**: FPS, bank card * **Amount**: transaction amount * **Status**: transaction status (succeeded, failed, pending, in_progress) * **Date** and time of the transaction creation * **Merchant**: your company name * **Fee**: amount withheld by the Bank for transaction processing * **Antifraud**: service comment (Passed, Failed) To download a **transaction report** for the [filtered period](#searching) in CSV format for further processing or for forwarding to your accounting department, click the **Download CSV** button in the top right corner. In the transaction card you can download a PDF receipt with the following details: masked card number, transaction date and time, status, type (payment, payout, or refund), and other data. You can provide it to your customers as an official confirmation upon request. The feature is already available for all transaction types—successful payments, payouts, and refunds. ### Date filter and AI search At the top of the transaction list, you will find a period filter. You can select 7 days, 30 days, 90 days, all time, or a custom UTC period. You can also use our AI search: simply enter a query in the search bar and get the most relevant result. For example, you can enter "Transfers over 15,000 rubles in the last quarter" in the search bar. ## How to get access To get access to the Dashboard, contact your Account Manager at Smart Glocal. Sign the access authorization document, specifying the employees' email addresses and full names. Please note that access is granted to the corporate domain outlined in the agreement. **How to log in:** 1. Wait for an email from Smart Glocal to your corporate email address provided during registration. The email will contain your first login credentials: **login (your email) and temporary password (a generated character combination)**. 2. Follow the link in the email. 3. Upon first login, change the temporary password to a permanent one and complete two-factor authentication—it is mandatory for all users. 2FA protects your account even if your password is compromised—access is impossible without confirmation from your device. For any questions regarding onboarding, please contact your Smart Glocal manager. --- ## API interaction > Source: /docs/reference/format ## API version Currently, two API versions are supported. >Please use the correct names for each version! | API v1 | API v2 | |--------------------|--------------------| | payment_method | **payout_details** | | payments | **payout_list** | | acquiring_payments | **payment_list** | ## Endpoint #### How to generate a request + /api/v{API version number} + Example: **API v1**: https://demo.smart-glocal.com/api/v1/session/start/payout **API v2**: https://demo.smart-glocal.com/api/v2/session/start/payout #### Server address - For testing: https://demo.smart-glocal.com - For live transactions: https://proxy.smart-glocal.com ## Request format All the data in requests to Smart Glocal and notifications from Smart Glocal is transmitted using the HTTP POST/GET methods. Message parameters are packed into a JSON object. ## Authentication In the headers of your requests to Smart Glocal, always pass the following data for authentication: - your project identifier - request signature #### Headers | Name | Mandatory | Type | Description | | --------------------- | --------- | ------ | ------------------------------------------------------------- | | X-PARTNER-PROJECT | + | string | Project identifier (from your Account Manager) | | X-PARTNER-SIGN | + | string | [Request signature](/docs/reference/format#request-signature) | | X-PARTNER-SUBMERCHANT | - | string | Payer's identifier (for legal entities) | #### Request example with authentication ### Request signature The signature is needed to verify the authenticity and integrity of requests. Smart Glocal verifies that the requests received are in fact from you (and are complete); you verify Smart Glocal's notifications the same way. To create and verify a signature, you will need a secret key and a public key. Using your public key Smart Glocal will verify signatures of your incoming payments. #### Generating a key pair You need to generate a pair of keys on your side using the RSA signature algorithm. #### Creating request body signature The signature must be transmitted together with the request to Smart Glocal. You need to sign the request body as a whole in the form in which it is sent to Smart Glocal's server (after serializing the request body into JSON to send it over HTTP). Use your secret key for signing the request. Create a signature using the SHA-256 algorithm. The resulting signature must then be transmitted in the Base64 format. #### Verifying incoming requests from Smart Glocal All outgoing requests from Smart Glocal are signed using Smart Glocal's own secret key. Using Smart Glocal's public key, you need to verify the signatures of the requests coming from Smart Glocal on your side. The algorithm used is SHA-256. The signature is transmitted in the Base64 format. ### Smart Glocal's public keys - [for live transactions](/assets/smgl_public.pem) - [for testing](/assets/smgl_public_demo.pem) ### Signature generation and validation examples ## Idempotency key An idempotency key is a unique request identifier. You can generate it and use it to ensure that no request with the same unique identifier is attempted more than once. For example, this way you can avoid duplicate payments and payouts. The idempotency key lifetime is 24 hours. ### Format Specify the idempotency key in the request header. | Name | Mandatory | Type | Description | | ----------------- | -------------- | ------ | ---------------------------------------------------- | | X-PARTNER-IDEMPOTENCY-KEY | - | string | Idempotency key (from 4 to 64 characters) | ### Example of a request with an idempotency key Methods supporting the idempotency key feature - [session/create](/docs/reference/methods/session-create) - [session/init/payout](/docs/reference/methods/session-init-payout) - [session/start/payout](/docs/reference/methods/session-start-payout) - [session/init/payment](/docs/reference/methods/session-init-payment) - [session/start/payment](/docs/reference/methods/session-start-payment) - [session/confirm](/docs/reference/methods/session-confirm) - [session/capture](/docs/reference/methods/session-capture) - [session/cancel](/docs/reference/methods/session-cancel) - [session/refund](/docs/reference/methods/session-refund) Errors - idempotency_key_params_mismatch - The key has already been used for another session - idempotency_key_already_exists - The previous request with the same key is still in progress - idempotency_key_not_supported - This method cannot be used with an idempotency key See more about the [Errors](/docs/reference/errors) --- ## Quick start > Source: /docs/before To start using our API, complete the following steps: 1. Apply on [Smart Glocal website](https://smart-glocal.com). 2. Chat with your Account Manager at Smart Glocal. - Issue a [secret key and a public key](/docs/reference/format#request-signature) and exchange the public keys. - Provide your Account Manager with the IP address of the host from which requests will be sent. If your IP address changes, please notify the Account Manager in advance to avoid possible connectivity issues. - Provide your Account Manager with a URL in your system at which you would like to receive the [webhooks](/docs/reference/webhooks) from Smart Glocal (i.e. notifications of events, for example successful payments and payouts). - Get your project identifier. 3. Perform [testing](/docs/reference/testing) (without real data). 4. Sign an agreement with Smart Glocal. 5. Exchange data for real operations and check that all the operations come through. - For payouts, top up your balance. - Server for live transactions: **proxy.smart-glocal.com** 6. Negotiate your start date and go live. --- ## Smart Glocal API > Source: /docs/landing Smart Glocal provides a collection of API methods that enable you to manage payouts and payments. Requests and responses are made in JSON format. We offer a testing environment that you can use to test API calls without involving live data. :::tip[AI-friendly] We now provide [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt) to enable seamless integration with AI-powered tools and agents. The llms.txt file offers a compact overview of our site structure and key sections, giving AI models the context they need to understand the project at a glance. The llms-full.txt includes the complete text of each page inline, giving AI assistants immediate access to the full documentation without additional fetches. You can reference these files directly in your AI tools—no more manual scraping or copy-pasting for every query. ::: Find out more about what we offer: - [Payments](/docs/payments/payment-intro) - [One-time payments by card](/docs/payments/one-time-payment) - [Delayed capture payments](/docs/payments/payment-capture) - [Recurring payments](/docs/payments/payment-recurring) - [Local card payments](/docs/payments/local-cards) - [Local bank-to-bank transfers](/docs/payments/india-accounts) - [Local APMs](/docs/payments/payment-pix) - [Telegram payments](/docs/payments/payment-telegram-bot-use) - [Payment refunds](/docs/payments/payment-refund) - [Our reports](/docs/finance/payouts-daily-report) - [Daily payouts report](/docs/finance/payouts-daily-report) - [Daily payments report](/docs/finance/payment-daily-report) - [Our methods](/docs/reference/methods/session-create) [**Start using our API**](/docs/before) --- ## Testing > Source: /docs/reference/testing Before performing operations with real money, you need to test everything in the test environment. The [interaction format](/docs/reference/format) and the way you make requests are the same as when working with actual data. The only two things that are different are the server address (https://demo.smart-glocal.com) to send requests to and the Smart Glocal [public key](/assets/smgl_public_demo.pem) to use. ## Data for test operations ### Bank cards > During testing, use at least one 3D Secure card and at least one not protected by 3D Secure. #### With 3D Secure - 2200774546102058 - 4000000000000002 - 5500000000000004 >To go successfully through 3D Secure, specify 12345. >To fail the procedure, specify any other value. #### Without 3D Secure - 4242424242424242 - 5101180000000007 ### Wallet Any value. ### Bank account Any value. ## Testing unsuccessful operations By default, all operations are successful. To test an unsuccessful scenario, specify one of the below values in the reference field of the [customer](/docs/reference/objects#customer) object. | Value | Result | | ----- | ---------------------------------------------------------------------------------------------------------------- | | thief (for payments only) | The payment will be canceled when the money is put on hold | | loser (for payments and payouts) | The payment will be canceled when the funds on hold are debited; the payment will fail | --- ## Payments > Source: /docs/payments/payment-intro Below is information you need to know before you start accepting payments. ## Countries and currency You can accept payments in **euro** from any country except those mentioned in the list below. Minimum transaction amount: **€10** Maximum transaction amount: **€1,000** Countries/regions you cannot accept payments from - Afghanistan - Belarus - Canada - Central African Republic - Crimea, Donetsk, Luhansk (Ukraine) - Cuba - DR Congo - Iran - North Korea - Mali - Myanmar - Sudan (North) - Syria - UK - US - Venezuela - Yemen - Zimbabwe [Parameters you need to pass when accepting a payment](/docs/payments/params) ### Types of cards accepted globally - **Mastercard** - **Visa** Please check with your Account Manager whether or not the cards below are available for accepting payments. - **Discover** - **JCB** ### Types of cards accepted locally - [Brazil](/docs/payments/brazil-cards): **American Express**, **ELO** - [Chile](/docs/payments/chile-cards): **American Express**, **CMR**, **Mach** - [Colombia](/docs/payments/colombia-cards): **Diners Club**, **Maestro Debit**, **Codensa** - [India](/docs/payments/india-cards): **American Express**, **Diners Club**, **Maestro Debit**, **RuPay** - [Indonesia](/docs/payments/indonesia-cards): **American Express**, **Maestro Debit**, **JCB** - [Mexico](/docs/payments/mexico-cards): **American Express**, **Carnet Credit**, **Carnet Debit** - [Nigeria](/docs/payments/nigeria-cards): **Verve** - [Thailand](/docs/payments/thailand-cards): **UnionPay**, **Diners Club**, **JCB** - [Türkiye](/docs/payments/turkiye-cards): **American Express**, **Maestro**, **Discover**, **Troy** - [Vietnam](/docs/payments/vietnam-cards): **Napas** ## Payments you can make Currently, the following payments are available: - [One-time payments by card](/docs/payments/one-time-payment) - [Delayed capture payments](/docs/payments/payment-capture) - [Local card payments](/docs/payments/local-cards) - [Local bank-to-bank transfers](/docs/payments/india-accounts) - [Local APMs](/docs/payments/payment-pix) - [Recurring payments](/docs/payments/payment-recurring) - [Telegram payments](/docs/payments/payment-telegram-bot-use) - [Payment refunds](/docs/payments/payment-refund) ## Merchant of Record Smart Glocal can act as the Merchant of Record (MoR) for your business. In the MoR model, Smart Glocal acts as the legal seller of record for each transaction, taking end-to-end financial and legal responsibility. #### Smart Glocal handles: - **Transaction execution**: processing payments, issuing confirmations, and generating receipts for your customers - **Tax and compliance**: tax registration, accurate collection, and remittance in confirmed jurisdictions - **Post-sale management**: risk management, chargebacks, disputes, and payment-related customer support #### You retain: - Full ownership of your product and the customer relationship - Net revenue (after settlement) This way you avoid the heavy compliance infrastructure and legal overhead typically required for cross-border selling. >Currently, the MoR model only applies to the sale of products subject to VAT at the standard rate. [Payment parameters you need in the MoR model](/docs/payments/mor) ## PCI DSS compliance You can pass card details with open parameters or use our [payment widget](/docs/widget/payment-widget). In both cases, you must comply with the PCI DSS requirements. ## Card identifier > To enable this functionality, please contact your Account Manager at Smart Glocal. If you do not store bank card details on your side and you need to understand which card the user is using and whether users' cards overlap, you can use the card identifier feature. > If you have multiple projects ([X-PARTNER-PROJECT](/docs/reference/format#authentication)), a card identifier may be the same or different for each project. Please inform your Account Manager which option you prefer. A card identifier is unique and is generated based on the card number and its expiration date. Its value is passed in the new parameter [card_id](/docs/reference/objects#card). This parameter can be passed during payments, recurring payments, and refunds. > A card identifier can not be used for making payments or for getting all linked cards. A card identifier is not a replacement for a token—if you use a token, you will receive both. ## Prices The prices for acquiring are given in your agreement with Smart Glocal. You can discuss them with your Account Manager. --- ## Delayed capture payments > Source: /docs/payments/payment-capture Delayed capture payments are widely used nowadays by all sorts of vendors as the delayed capture feature provides a number of benefits. For example, delayed capture payments allow you to: - Prevent fraud by giving you enough time to verify a customer’s credentials before delivering a product or service. - Charge customers after delivering them products or services. - Reduce the number of chargebacks and refunds in case the transaction ends up canceled. ## How it works All payments consist of two key processes: authorization (when the bank verifies if the needed amount is available and places a hold on this amount) and capture (when the bank clears the payment and debits it). In case of regular payments, these two processes happen almost at the same time and are not perceived by end users. In case of delayed capture payments, however, you authorize the card, but wait to capture the funds. So, the funds are kept blocked on the user's card till your instruction to debit them. ## How to enable delayed capture payments If you would like to perform payments with delayed capture, please contact your Account Manager on the matter. ## How long the hold period is By default, the money is held for **3 days 23 hours**. If you do not debit or unblock it before the end of this period, the money will get unblocked automatically. If you need the money to be debited rather than unblocked after the hold period end or the money to be held for a different period, please contact your Account Manager. ## How to make a delayed capture payment Below you will find two ways of making a delayed capture payment. To create a delayed capture payment, complete the following steps: 1. Create a payment session sending a [session/create](/docs/reference/methods/session-create) request. >Alternatively, you can use the [session/init/payment](/docs/reference/methods/session-init-payment) method. In this case, specify all the payment parameters right away and skip the next step. 2. Send a [session/start/payment](/docs/reference/methods/session-start-payment) request to start the payment. 3. Wait for a [ready_to_confirm](/docs/reference/webhooks/ready-to-confirm) webhook, which means that Smart Glocal is ready to perform the payment and is waiting for your confirmation. 4. Send a [session/confirm](/docs/reference/methods/session-confirm) request to confirm the operation or a [session/cancel](/docs/reference/methods/session-cancel) request to cancel the payment. 5. If you receive an [action_required](/docs/reference/webhooks/action-required) webhook, it means that you need to take an additional action to perform the payment. For instance, the user might need to go through 3D Secure. Redirect the user for 3D Secure authentication using the link from the webhook. 6. Wait for a [ready_to_capture](/docs/reference/webhooks/ready-to-capture) webhook from Smart Glocal. It means that a hold has been successfully placed on the amount. You can capture the amount immediately or later. 7. When the time is ready, capture the amount put on hold ([session/capture](/docs/reference/methods/session-capture)) or decline the payment ([session/cancel](/docs/reference/methods/session-cancel)) unblocking the amount. 8. Wait for a [payment_finished](/docs/reference/webhooks/payment-finished) webhook containing the result of the payment. If the [status](/docs/reference/objects#status) is succeeded, the payment was successful. ### Sequence diagram of delayed capture payments with open parameters ![DelayedCapturePCIDSS](/img/docs/delayed_capture_pcidss.png) To create a delayed capture payment using our payment widget, complete the following steps: 1. Complete [Steps 1–5](/docs/widget/payment-widget). > If you receive an action_required webhook, send the HTTP 200 OK in response but do nothing, as the user will be redirected for 3D Secure within the widget. 2. Wait for a [ready_to_confirm](/docs/reference/webhooks/ready-to-confirm) webhook. When you received it, it means that Smart Glocal is ready to make the payment and is waiting for your confirmation. 3. Confirm ([session/confirm](/docs/reference/methods/session-confirm)) or cancel the payment ([session/cancel](/docs/reference/methods/session-cancel)). 4. Wait for a [ready_to_capture](/docs/reference/webhooks/ready-to-capture) webhook from Smart Glocal. It means that a hold has been successfully placed on the amount. You can capture the amount immediately or later. 5. When the time is ready, capture the amount put on hold ([session/capture](/docs/reference/methods/session-capture)) or decline the payment ([session/cancel](/docs/reference/methods/session-cancel)) unblocking the amount. 6. Wait for a [payment_finished](/docs/reference/webhooks/payment-finished) webhook containing the result of the payment. If the [status](/docs/reference/objects#status) is succeeded, the payment was successful. ### Sequence diagram of delayed capture payments with the payment widget ![DelayedCaptureWidget](/img/docs/delayed_capture_widget.png) --- ## One-time payments > Source: /docs/payments/one-time-payment Below you will find two general scenarios of how to make a one-time payment. You can pass card details with open parameters or use the payment form. In both cases, you must comply with the PCI DSS requirements. > All API operations are carried out within a [payment session](/docs/reference/objects#payment_session). One payment session can include several operations: for example, you can accept and then refund a payment. :::info[] Check the [parameters](/docs/payments/params) you need to pass when accepting a payment from [these countries](/docs/payments/payment-intro#countries). ::: To create a one-time payment, complete the following steps: 1. Create a payment session sending a [session/create](/docs/reference/methods/session-create) request. >Alternatively, you can use the [session/init/payment](/docs/reference/methods/session-init-payment) method. In this case, specify all the payment parameters right away and skip the next step. 2. Send a [session/start/payment](/docs/reference/methods/session-start-payment) request to start the payment. 3. Wait for a [ready_to_confirm](/docs/reference/webhooks/ready-to-confirm) webhook. When you receive it, it means that Smart Glocal is ready to make the payment and is waiting for your confirmation. 4. Send a [session/confirm](/docs/reference/methods/session-confirm) request or a [session/cancel](/docs/reference/methods/session-cancel) request to confirm or cancel the operation. 5. If you receive an [action_required](/docs/reference/webhooks/action-required) webhook, it means that you need to take an additional action to perform the payment. For instance, the user might need to go through 3D Secure. Redirect the user for 3D Secure authentication using the link from the webhook. 6. Wait for a [payment_finished](/docs/reference/webhooks/payment-finished) webhook containing the result of the payment. If the [status](/docs/reference/objects#status) is succeeded, the payment was successful. #### Sequence diagram of payments without use of the payment form ![SequencePCIDSS](/img/docs/payment_pcidss.png) To create a one-time payment using our payment widget, complete the following steps: 1. Complete [Steps 1–5](/docs/widget/payment-widget). > If you receive an action_required webhook, send the HTTP 200 OK in response but do nothing, as the user will be redirected for 3D Secure within the widget. 2. Wait for a [ready_to_confirm](/docs/reference/webhooks/ready-to-confirm) webhook. When you received it, it means that Smart Glocal is ready to make the payment and is waiting for your confirmation. 3. Send a [session/confirm](/docs/reference/methods/session-confirm) request or a [session/cancel](/docs/reference/methods/session-cancel) request to confirm or cancel the operation. 4. Wait for a [payment_finished](/docs/reference/webhooks/payment-finished) webhook containing the result of the payment. If the [status](/docs/reference/objects#status) is succeeded, the payment was successful. #### Sequence diagram of payments with the payment widget ![SequenceWidget](/img/docs/payment_widget.png) --- ## Payment parameters > Source: /docs/payments/params When you accept a payment from [these countries](/docs/payments/payment-intro#countries), make sure you pass all the required parameters. :::info[] Currently, only one-time payments are available. ::: ## Payments through our widget If you use our payment widget, when you [create a session](/docs/widget/payment-widget#making-a-payment-using-the-widget), make sure you pass the following parameters with sender information: - full_name - first_name - last_name - city - street - ipv4 - postal_code (up to 6 digits) - email :::info[] If you do not pass these parameters, we will generate them on our own (except for the first and last names), but the conversion rate might be worse. ::: #### Example of a session/create request ## Payments without our widget When you make a payment, make sure you pass the following parameters with sender information: - full_name - first_name—mandatory - last_name—mandatory - city - street - ipv4—mandatory - postal_code (up to 6 digits) - email You can pass these parameters within any of the methods: - session/create - session/start/payment - session/init/payment :::info[] If you do not pass these parameters, we will generate them on our own (except for the first and last names), but the conversion rate might be worse. ::: #### Example of a session/create request --- ## Payment refunds > Source: /docs/payments/payment-refund You can return a successful payment to the sender as follows: - Within the **refund** operation—this is the most commonly encountered situation, the payment can be returned totally or partially. >Please check with your Account Manager if partial refunds are enabled for you. - Within the **chargeback** procedure—this procedure cannot be initiated by the merchant, a notification about it is sent by Smart Glocal. In this case, the amount is withdrawn from the compensation. :::warning[] For payments accepted from [these countries](/docs/payments/payment-intro#countries), you can request a refund only the next day after the payment. ::: ## How to perform a refund ### Step 1. Send a refund request To perform a refund, send a [session/refund](/docs/reference/methods/session-refund) request. In the session_id field, pass the identifier of the successful [payment session](/docs/reference/objects#payment_session) for the payment you need to refund. In amount_details.amount, specify the amount of the refund. If you leave this blank, the money will be refunded in full. #### Request example ### Step 2. Wait to be notified of the results After the refund is completed, Smart Glocal will send you a [payment_refunded](/docs/reference/webhooks/payment-refunded) webhook with the results. #### Webhook example --- ## Local card payments > Source: /docs/payments/local-cards To make local card payment, use the [standard steps](/docs/payments/one-time-payment). At the same time, in accordance with local requirements, you will be required to provide additional information about the payer. General rules: - The currency must always match that of the country of payment. - document—payer's national identifier (the format depends on the country). - msisdn—phone number without the + sign, up to 15 characters. - Address fields (city, street, postal_code, etc.) may be mandatory for cross-border transactions only. - All string fields have length restrictions—please ensure client-side validation is observed. Check the currency and the set of required sender parameters in the table below: | Country | Currency (ISO 4217) | Required sender parameters | Notes | |---------|------------------------|-------------------------|------------------| | [Brazil](/docs/payments/brazil-cards) |BRL | full_name, email | Minimum amount: 1 BRL | | [Chile](/docs/payments/chile-cards) | CLP | full_name, email | Minimum amount: 50 CLP| | [Colombia](/docs/payments/colombia-cards) | COP | full_name, email, document | Minimum amount: 169 COP| | [India](/docs/payments/india-cards) |INR | full_name, email, document, msisdn | Additionally for cross-border transactions: state, city, street, postal_code, building| | [Indonesia](/docs/payments/indonesia-cards) | IDR | full_name, email, document | Minimum amount: 11,000 IDR| | [Mexico](/docs/payments/mexico-cards) | MXN | full_name, email |Minimum amount: 1 MXN| | [Nigeria](/docs/payments/nigeria-cards) | NGN | full_name, email |Minimum amount: 51 NGN| | [Philippines](/docs/payments/philippines-cards) | PHP | full_name, email, document |Minimum amount: 1 PHP| | [Thailand](/docs/payments/thailand-cards) | THB | full_name, email, document |Minimum amount: 1 THB| | [Türkiye](/docs/payments/turkiye-cards) | TRY | full_name, email, document |Minimum amount: 1 TRY| | [Vietnam](/docs/payments/vietnam-cards) | VND | full_name, email, document | Minimum amount: 5,000 VND | --- ## Local card payments in Brazil > Source: /docs/payments/brazil-cards You can make local card payments in Brazil. Currency: **BRL** Minimum payment amount: **1 BRL** Maximum payment amount: **unlimited** Available payment systems: **Visa Credit, Visa Debit, Mastercard Credit, Mastercard Debit, American Express, ELO** To make a payment, complete the [standard steps](/docs/payments/one-time-payment). :::info[] If you use our widget, pass the mandatory parameters in the session/create method. Otherwise, you can pass the mandatory parameters either in session/create or in session/start/payment. ::: ### Required sender parameters [Check all the required parameters](/docs/reference/methods/session-start-payment) | Name | Type | Description | |---------------------------------|--------|------------------------------------------------------------------| | participant_details | object | [Information on the participants](/docs/reference/objects#participant_details) | |   sender | object | [Sender details](/docs/reference/objects#sender) | |     full_name | string | Sender's full name (3–50 characters) | |     email | string | Sender's email address (up to 64 characters before @) | |     document | string | CPF number (11 digits) or CNPJ number (14 digits) | ### Request example --- ## Local card payments in Chile > Source: /docs/payments/chile-cards You can make local card payments in Chile. Currency: **CLP** Minimum payment amount: **50 CLP** Maximum payment amount: **unlimited** Available payment systems: **Visa Credit, Visa Debit, Mastercard Credit, Mastercard Debit, American Express, CMR, Mach** To make a payment, complete the [standard steps](/docs/payments/one-time-payment). :::info[] If you use our widget, pass the mandatory parameters in the session/create method. Otherwise, you can pass the mandatory parameters either in session/create or in session/start/payment. ::: ### Required sender parameters [Check all the required parameters](/docs/reference/methods/session-start-payment) | Name | Type | Description | |---------------------------------|--------|------------------------------------------------------------------| | participant_details | object | [Information on the participants](/docs/reference/objects#participant_details) | |   sender | object | [Sender details](/docs/reference/objects#sender) | |     full_name | string | Sender's full name (3–50 characters) | |     email | string | Sender's email address (up to 64 characters before @) | ### Request example --- ## Local card payments in Colombia > Source: /docs/payments/colombia-cards You can make local card payments in Colombia. Currency: **COP** Minimum payment amount: **169 COP** Maximum payment amount: **unlimited** Available payment systems: **Visa Credit, Visa Debit, Mastercard Credit, Mastercard Debit, Diners Club, Maestro Debit, Codensa** To make a payment, complete the [standard steps](/docs/payments/one-time-payment). :::info[] If you use our widget, pass the mandatory parameters in the session/create method. Otherwise, you can pass the mandatory parameters either in session/create or in session/start/payment. ::: ### Required sender parameters [Check all the required parameters](/docs/reference/methods/session-start-payment) | Name | Type | Description | |---------------------------------|--------|------------------------------------------------------------------| | participant_details | object | [Information on the participants](/docs/reference/objects#participant_details) | |   sender | object | [Sender details](/docs/reference/objects#sender) | |     full_name | string | Sender's full name (3–50 characters) | |     email | string | Sender's email address (up to 64 characters before @) | |     document | string | CC or NIT (6 to 11 digits) | ### Request example --- ## Local card payments in India > Source: /docs/payments/india-cards You can make local card payments in India. Currency: **INR** Minimum payment amount: **1 INR** Maximum payment amount: **unlimited** Available payment systems: **Visa, Visa Debit, Mastercard, Mastercard Debit, American Express, Diners Club, Maestro Debit, RuPay** To make a payment, complete the [standard steps](/docs/payments/one-time-payment). :::info[] If you use our widget, pass the mandatory parameters in the session/create method. Otherwise, you can pass the mandatory parameters either in session/create or in session/start/payment. ::: ### Required sender parameters [Check all the required parameters](/docs/reference/methods/session-start-payment) | Name | Type | Description | |---------------------------------|--------|------------------------------------------------------------------| | participant_details | object | [Information on the participants](/docs/reference/objects#participant_details) | |   sender | object | [Sender details](/docs/reference/objects#sender) | |     full_name | string | Sender's full name (3–50 characters) | |     email | string | Sender's email address (up to 64 characters before @) | |     document | string | Ten-character alphanumeric identifier (PAN) | |     msisdn | string | Phone number (up to 15 characters, without + ) | |     state | string | Sender's state (up to 10 characters) **Mandatory for cross-border transactions only** | |     city | string | Sender's city (3–50 characters) **Mandatory for cross-border transactions only** | |     street | string | Sender's street (4–100 characters) **Mandatory for cross-border transactions only** | |     postal_code | string | Sender's postal code (up to 6 characters) **Mandatory for cross-border transactions only** | |     building | string | Sender's building **Mandatory for cross-border transactions only** | ### Request example --- ## Local card payments in Indonesia > Source: /docs/payments/indonesia-cards You can make local card payments in Indonesia. Currency: **IDR** Minimum payment amount: **11,000 IDR** Maximum payment amount: **unlimited** Available payment systems: **Visa, Visa Debit, Mastercard, Mastercard Debit, American Express, Maestro Debit, JCB** To make a payment, complete the [standard steps](/docs/payments/one-time-payment). :::info[] If you use our widget, pass the mandatory parameters in the session/create method. Otherwise, you can pass the mandatory parameters either in session/create or in session/start/payment. ::: ### Required sender parameters [Check all the required parameters](/docs/reference/methods/session-start-payment) | Name | Type | Description | |---------------------------------|--------|------------------------------------------------------------------| | participant_details | object | [Information on the participants](/docs/reference/objects#participant_details) | |   sender | object | [Sender details](/docs/reference/objects#sender) | |     full_name | string | Sender's full name (3–50 characters) | |     email | string | Sender's email address (up to 64 characters before @) | |     document | string | NIK number (16 digits) | ### Request example --- ## Local card payments in Mexico > Source: /docs/payments/mexico-cards You can make local card payments in Mexico. Currency: **MXN** Minimum payment amount: **1 MXN** Maximum payment amount: **unlimited** Available payment systems: **Visa Credit, Visa Debit, Mastercard Credit, Mastercard Debit, American Express, Carnet Credit, Carnet Debit** To make a payment, complete the [standard steps](/docs/payments/one-time-payment). :::info[] If you use our widget, pass the mandatory parameters in the session/create method. Otherwise, you can pass the mandatory parameters either in session/create or in session/start/payment. ::: ### Required sender parameters [Check all the required parameters](/docs/reference/methods/session-start-payment) | Name | Type | Description | |---------------------------------|--------|------------------------------------------------------------------| | participant_details | object | [Information on the participants](/docs/reference/objects#participant_details) | |   sender | object | [Sender details](/docs/reference/objects#sender) | |     full_name | string | Sender's full name (3–50 characters) | |     email | string | Sender's email address (up to 64 characters before @) | ### Request example --- ## Local card payments in Nigeria > Source: /docs/payments/nigeria-cards You can make local card payments in Nigeria. :::info[] MIT recurring payments are not available. ::: Currency: **NGN** Minimum payment amount: **51 NGN** Maximum payment amount: **unlimited** Available payment systems: **Visa, Visa Debit, Mastercard, Mastercard Debit, Verve** To make a payment, complete the [standard steps](/docs/payments/one-time-payment). :::info[] If you use our widget, pass the mandatory parameters in the session/create method. Otherwise, you can pass the mandatory parameters either in session/create or in session/start/payment. ::: ### Required sender parameters [Check all the required parameters](/docs/reference/methods/session-start-payment) | Name | Type | Description | |---------------------------------|--------|------------------------------------------------------------------| | participant_details | object | [Information on the participants](/docs/reference/objects#participant_details) | |   sender | object | [Sender details](/docs/reference/objects#sender) | |     full_name | string | Sender's full name (3–50 characters) | |     email | string | Sender's email address (up to 64 characters before @) | ### Request example --- ## Local card payments in the Philippines > Source: /docs/payments/philippines-cards You can make local card payments in the Philippines. Currency: **PHP** Minimum payment amount: **1 PHP** Maximum payment amount: **unlimited** Available payment systems: **Visa Credit, Visa Debit, Mastercard Credit, Mastercard Debit** To make a payment, complete the [standard steps](/docs/payments/one-time-payment). :::info[] If you use our widget, pass the mandatory parameters in the session/create method. Otherwise, you can pass the mandatory parameters either in session/create or in session/start/payment. ::: ### Required sender parameters [Check all the required parameters](/docs/reference/methods/session-start-payment) | Name | Type | Description | |---------------------------------|--------|------------------------------------------------------------------| | participant_details | object | [Information on the participants](/docs/reference/objects#participant_details) | |   sender | object | [Sender details](/docs/reference/objects#sender) | |     full_name | string | Sender's full name (3–50 characters) | |     email | string | Sender's email address (up to 64 characters before @) | |     document | string | PSN number (12 digits) | ### Request example --- ## Local card payments in Thailand > Source: /docs/payments/thailand-cards You can make local card payments in Thailand. Currency: **THB** Minimum payment amount: **1 THB** Maximum payment amount: **unlimited** Available payment systems: **Visa, Visa Debit, Mastercard, Mastercard Debit, UnionPay, Diners Club, JCB** To make a payment, complete the [standard steps](/docs/payments/one-time-payment). :::info[] If you use our widget, pass the mandatory parameters in the session/create method. Otherwise, you can pass the mandatory parameters either in session/create or in session/start/payment. ::: ### Required sender parameters [Check all the required parameters](/docs/reference/methods/session-start-payment) | Name | Type | Description | |---------------------------------|--------|------------------------------------------------------------------| | participant_details | object | [Information on the participants](/docs/reference/objects#participant_details) | |   sender | object | [Sender details](/docs/reference/objects#sender) | |     full_name | string | Sender's full name (3–50 characters) | |     email | string | Sender's email address (up to 64 characters before @) | |     document | string | Thai Identity Card number (13 digits) | ### Request example --- ## Local card payments in Türkiye > Source: /docs/payments/turkiye-cards You can make local card payments in Türkiye. :::info[] MIT recurring payments are not available. ::: Currency: **TRY** Minimum payment amount: **1 TRY** Maximum payment amount: **unlimited** Available payment systems: **Visa Credit, Visa Debit, Mastercard Credit, Mastercard Debit, American Express, Maestro, Discover, Troy** To make a payment, complete the [standard steps](/docs/payments/one-time-payment). :::info[] If you use our widget, pass the mandatory parameters in the session/create method. Otherwise, you can pass the mandatory parameters either in session/create or in session/start/payment. ::: ### Required sender parameters [Check all the required parameters](/docs/reference/methods/session-start-payment) | Name | Type | Description | |-------------------------------------|--------|--------------------------------------------------------------------------------| | participant_details | object | [Information on the participants](/docs/reference/objects#participant_details) | |   sender | object | [Sender details](/docs/reference/objects#sender) | |     full_name | string | Sender's full name (3–50 characters) | |     email | string | Sender's email address (up to 64 characters before @) | |     document | string | T.C. Kimlik No. (5–20 digits) | ### Request example --- ## Local card payments in Vietnam > Source: /docs/payments/vietnam-cards You can make local card payments in Vietnam. Currency: **VND** Minimum payment amount: **5000 VND** Maximum payment amount: **unlimited** Available payment systems: **Visa Credit, Mastercard Credit, Napas** To make a payment, complete the [standard steps](/docs/payments/one-time-payment). :::info[] If you use our widget, pass the mandatory parameters in the session/create method. Otherwise, you can pass the mandatory parameters either in session/create or in session/start/payment. ::: ### Required sender parameters [Check all the required parameters](/docs/reference/methods/session-start-payment) | Name | Type | Description | |-------------------------------------|--------|-------------------------------------------------------| | participant_details | object | [Information on the participants](/docs/reference/objects#participant_details) | |   sender | object | [Sender details](/docs/reference/objects#sender) | |     full_name | string | Sender's full name (3–50 characters) | |     email | string | Sender's email address (up to 64 characters before @) | |     document | string | 9 or 13 digits identifier number (VNID) | ### Request example --- ## Recurring payments. Preconditions > Source: /docs/payments/payment-recurring Recurring payments are very useful in the following situations: - a customer needs to make repeated payments (for example, pay a monthly subscription) and authorizes the provider to take these payments without their interaction ([MIT payments](/docs/payments/payment-recurringMIT)) - a customer makes regular purchases at a place and wants their card details saved not to enter them every time ([CIT payments](/docs/payments/payment-recurringCIT)) > Currently, recurring payments can only be accepted from a bank card. ## Main steps Generally, to start accepting recurring payments, you need to complete the following two steps: 1. [Get the user's consent to](/docs/payments/payment-recurring#step-1-get-the-users-consent) recurring payments. 2. [Perform a successful payment](/docs/payments/payment-recurring#step-2-perform-a-successful-payment) that will recur and get a token. After completing these steps, you can proceed to accept [MIT recurring payments](/docs/payments/payment-recurringMIT) or [CIT recurring payments](/docs/payments/payment-recurringCIT). ### Step 1. Get the User's Consent To perform recurring payments, you need an explicit consent of the user. You need it not only because you are going to make payments without the user being involved (MIT payments) or because you store their bank card details (CIT payments), but also for any dispute situations (e.g. if the user complaints about an unauthorized debit). How to do it: - Describe the payment terms to make sure the user will read them. - Ask the user to confirm they understand and agree to the terms (e.g. add an unambiguous checkbox like **Save card**, **Enable recurring payments**, **Enable recurring donations**, etc.). The checkbox can be on your side (in this case, you will decide how it looks and where it is located) or on our side—in our [payment widget](/docs/widget/payment-widget). ### Step 2. Perform a successful payment Make a [one-time payment](/docs/payments/one-time-payment) you plan to make a recurring one. >In the [session/create](/docs/reference/methods/session-create) or [session/start/payment](/docs/reference/methods/session-start-payment) request, pass true in the recurrent parameter of the [payment_options](/docs/reference/objects#payment_options) object. #### Example If this payment is successfully performed, you will receive a token in the [recurrent](/docs/reference/objects#recurrent_info) object of the [payment_finished](/docs/reference/webhooks/payment-finished) webhook. > When making a payment with the [widget](https://developer.smart-glocal.com/docs/widget/payment-widget), you have two options: > - get the user's consent earlier, pass recurrent: true in the [session/create](/docs/reference/methods/session-create) request, and show the user the standard widget > - display the user the widget with the **I agree to recurring payments** checkbox (see an [example](https://developer.smart-glocal.com/docs/reference/methods/token-method#getting-a-token-for-the-payment-form-widget-with-the-recurrent-payments-option)). In this case, when the user checks the **I agree to recurring payments** checkbox (i.e. agrees to recurring payments from their card), you will receive a token in the [recurrent](/docs/reference/objects#recurrent_token) object of the [payment_finished](/docs/reference/webhooks/payment-finished) webhook. Make a [one-time payment](/docs/payments/one-time-payment) you plan to make a recurring one using our widget. If this payment is successfully performed, you will receive a token in the [recurrent](/docs/reference/objects#recurrent_token) object of the [payment_finished](/docs/reference/webhooks/payment-finished) webhook. > In the last4 field of the [card](/docs/reference/objects#card) object you will get the last for digits of the card and can use this information to let the user know which card is used. Now, proceed to accept [MIT recurring payments](/docs/payments/payment-recurringMIT) or [CIT recurring payments](/docs/payments/payment-recurringCIT). ### Managing your tokens When you create a token, it becomes active (is_active: true) and you can perform payments using the token. The token may expire (e.g. if the associated bank card expires). If a token is inactive (is_active: false) or expired, the payment will fail. To learn the token status, send a [token/info](/docs/reference/methods/token-info) request. In the type parameter, pass the recurrent_token value, in the recurrent_token.token parameter pass the token. In return, you will get [info](/docs/reference/objects#recurrent_token_info) with the token expiration date (finished_at) and token status (is_active). If is_active: true, you can perform payments using this token. If you don't want to use a token for payments anymore (e.g. a user disabled recurring payments), send a [recurrent/disable](/docs/reference/methods/recurrent-disable) request. In response, you will receive [recurrent](/docs/reference/objects#recurrent_info). If is_active: false, it means the token is disabled. ### Sequence diagrams ![](/img/docs/recP.png) ![](/img/docs/recP_widget.png) --- ## CIT recurring payments > Source: /docs/payments/payment-recurringCIT CIT recurring payments (Customer Initiated Transaction) allow accepting payments and debit money using a token, i.e. when the customer does not need to re-enter their card details. These payments can be used for paying different services (amounts) at the same place. To make such payments we carry out an additional 3DS verification of the customer, so make sure you use the project identifier eligible for 3DS. > Note that you cannot use our widget to accept CIT payments, since our widget cannot display pre-populated card details. But you can use the last four card digits we return in the last4 field of the [card](/docs/reference/objects#card) object in the [payment_finished](/docs/reference/webhooks/payment-finished) webhook. Once you have a [token](/docs/payments/payment-recurring#main-steps), you can start accepting CIT recurring payments. ## Making a CIT recurring payment To make a CIT recurring payment, complete the following steps: 1. Create a payment session sending a [session/create](/docs/reference/methods/session-create) request. >Alternatively, you can use the [session/init/payment](/docs/reference/methods/session-init-payment) method. In this case, specify all the payment parameters right away as it is specified in the next step and skip the next step. 2. Send a [session/start/payment](/docs/reference/methods/session-start-payment) request to start the CIT recurring payment. Make sure you send: - initiator: client in the [recurrent](/docs/reference/objects#recurrent_token) object of payment_details - a URL in the return_url parameter of the [payment_options](/docs/reference/objects#payment_options) object to redirect the customer back after the payment complete. Example 3. Wait for a [ready_to_confirm](/docs/reference/webhooks/ready-to-confirm) webhook. When you receive it, it means that Smart Glocal is ready to make the payment and is waiting for your confirmation. 4. Send a [session/confirm](/docs/reference/methods/session-confirm) request or a [session/cancel](/docs/reference/methods/session-cancel) request to confirm or cancel the operation. 5. Wait for an [action_required](/docs/reference/webhooks/action-required) webhook from Smart Glocal. It will contain a [redirect](/docs/reference/objects#redirect) object. Example 6. Redirect the customer to the URL passed in customer_interaction.redirect.url. **Note that the redirect method can be GET or POST.** >Note that after completion of 3DS verification, the customer returns to the URL that was passed as return_url. According to the method used, POST or GET, you might need to convert the POST format to GET to avoid possible format processing issues. 7. Wait for a [payment_finished](/docs/reference/webhooks/payment-finished) webhook from Smart Glocal. The webhook will contain the recurring [payment status information](/docs/reference/objects#status). Example ### Sequence diagram of CIT recurring payments ![](/img/docs/cit_recurring_payment.png) --- ## MIT recurring payments > Source: /docs/payments/payment-recurringMIT MIT recurring payments (Merchant Initiated Transaction) enable you to accept a payment without involving the user, using a token. These payments can be used for paying: - utilities and mobile phone bills - any memberships - any subscriptions Once you have a [token](/docs/payments/payment-recurring#main-steps), you can start accepting MIT recurring payments. ## Accepting payments using a token 1. Create a payment session sending a [session/create](/docs/reference/methods/session-create) request. >Alternatively, you can use the [session/init/payment](/docs/reference/methods/session-init-payment) method. In this case, specify all the payment parameters right away as it is specified in the next step and skip the next step. 2. Send a [session/start/payment](/docs/reference/methods/session-start-payment) request with the recurrent payment type. Instead of a bank card, pass the token. Optionally, you can pass initiator: merchant in the [recurrent](/docs/reference/objects#recurrent_token) object of payment_details. Example 3. Wait for a [ready_to_confirm](/docs/reference/webhooks/ready-to-confirm) webhook. 4. Send a [session/confirm](/docs/reference/methods/session-confirm) request or a [session/cancel](/docs/reference/methods/session-cancel) request to confirm or cancel the operation. 5. Wait for a [payment_finished](/docs/reference/webhooks/payment-finished) webhook containing the [payment status information](/docs/reference/objects#status). ### Sequence diagram of MIT recurring payments ![](/img/docs/mit_recurring_payment.png) --- ## How to connect our Telegram bot > Source: /docs/payments/payment-telegram-bot-connect If you have a bot in Telegram, you can connect your bot to our payment bot and start accepting payments. To do this, complete the following steps: 1. Send /mybots to @BotFather to obtain the list of your bots and click the name of a bot you need to connect to our payment bot. ![](/img/docs/telegram/Telegram_BotFather4.png) 2. In the menu, click **Payments**. ![](/img/docs/telegram/Telegram_BotFather5.png) 3. In the list of payment providers, select **Smart Glocal** (use the **<<** and **>>** buttons to navigate through the list). ![](/img/docs/telegram/Telegram_BotFather8.png) 4. Connect one of the Smart Glocal bots: the **Smart Glocal Test** bot allows making payments safely in a test environment, while the **Smart Glocal Live** bot is used to perform real payments. ![](/img/docs/telegram/Telegram_BotFather9.png) To connect the **Smart Glocal Test** bot: 1. Select **Connect Smart Glocal Test** and click **Start**. 2. To confirm your intention to use the bot, click the code in the message to copy it, paste it, and send it to the Smart Glocal bot. ![](/img/docs/telegram/Telegram_BotFather10.png) To connect the **Smart Glocal Live** bot: 1. Select **Connect Smart Glocal Live** and click **Start**. 2. To confirm your intention to use the bot, send the code you got from your Account Manager (if you do not have the code, contact us at [hello@smart-glocal.com](mailto:hello@smart-glocal.com)). ![](/img/docs/telegram/Telegram_BotFather11.png) As a result of the above steps, @BotFather will issue a **provider token** you will need to send invoices to your customers. Now, you can proceed to accept payments [using your bot](/docs/payments/payment-telegram-bot-use). --- ## How to accept payments using your Telegram bot > Source: /docs/payments/payment-telegram-bot-use > The information below is provided for bots that use [Telegram API](https://core.telegram.org/bots/api). For bots created using other services, refer to the appropriate API description. > Note that idempotency keys cannot be used. ## Making a payment using your bot To accept payments using your bot connected with the Smart Glocal bot, complete the following steps: 1. To be able to send invoices to your customers, call the [sendinvoice](https://core.telegram.org/bots/api#sendinvoice) method from your bot. Make sure you include all the mandatory parameters along with the provider_token value you got from @BotFather after connecting your bot to the Smart Glocal bot. If required, you can send some extra parameters within the provider_data object. Extra parameters email - email address (string) state - U.S. state of residence (2 characters, string) city - city of residence (50 characters, string) address line - address (200 characters, string) full_name - full name (string) postal_code - postal code (50 characters, string) country_iso2 - country code (ISO 3166-1 alpha-2) (2 characters, string) country_iso3 - country code (ISO 3166-1 alpha-3) (3 characters, string) ipv4 - IPv4 address (string) Request example 2. In response Telegram will render a form containing all the required fields you passed in the request above. 3. After the customer completes the fields, Telegram renders a payment form. 4. After the customer clicks **Pay**, Telegram will send a webhook with the [PreCheckoutQuery](https://core.telegram.org/bots/api#precheckoutquery) object. 5. Your bot should send [answerPreCheckoutQuery](https://core.telegram.org/bots/api#answerprecheckoutquery) in response. 6. If 3DS is required, you will receive an [action_required](/docs/reference/webhooks/action-required) webhook and Telegram will redirect the customer for 3DS. 7. Once the payment is successfully completed: - the customer will see the payment result on the screen - you will receive a [payment_finished](/docs/reference/webhooks/payment-finished) webhook from Smart Glocal (please reply with 200 OK to it) - Telegram will send you a payment confirmation containing the [SuccessfulPayment](https://core.telegram.org/bots/api#successfulpayment) object with the provider_payment_charge_id parameter (transaction ID) (store this ID for future references) ## Recurring payments via Telegram Telegram allows storing a customer's credit card data after their first payment and handle further (recurring) payments without involving the customer using a recurring payment token. You can save a customer's card data if the customer checks the respective checkbox when paying: ![](/img/docs/telegram/Telegram_BotFather12.png) Alternatively, you can pass the provider_data object with the "save_card": true parameter in the [sendinvoice](https://core.telegram.org/bots/api#sendinvoice) method. To know more about recurring payments, see [here](/docs/payments/payment-recurring). ### Sequence diagram of payments made using the Telegram bot ![](/img/docs/telegram/telegram_bot_payment.png) --- ## Daily payments report > Source: /docs/finance/payment-daily-report The daily report is sent in the XLSX or CSV format to the email address specified in your agreement with Smart Glocal. To receive the reports in another way (for example, via SFTP), please contact your Account Manager. ## How to use the report The report sent by Smart Glocal contains a list of all successful operations for a day (24 hours). You need to check the operations on your side against those in the report. In case of any discrepancy, contact our support team. The timeframe for making corrections is specified in your agreement with Smart Glocal. ## Report file name _YYYY-MM-DD_YYYY-MM-DD ## Report fields | Field name | Description | Field length | Example | | ----------------- | ---------------------------- | ------------ | --------------- | | **ID** | Smart Glocal payment identifier | 15–32 | pm_3783638 | | **paymentSessionId** | Payment session identifier | 0–100 | ps_3748383 | | **Project name** | Name of your project on Smart Glocal's side | 2–100 | acquiring_card | | **Type of payment** | Payment type. Options: Adjustment, Advice, Refund, Compensation, Recurrent. [More information](#payment-types) | 10–16 | Advice | | **Amount** | Total of the operation | 1–12 | 110 | | **Currency amount** | Transaction currency | 3 | USD | | **Fee** | Fee according to the contract (a negative value) | 1–12 | -2 | | **Currency fee** | Fee currency | 3 | USD | | **Settlement** | Total of the settlement Smart Glocal must transfer to you | 1–12 | 500 | | **Currency settlement** | Settlement amount currency | 3 | USD | | **Transaction date and time** | Date and time of the transaction on Smart Glocal's side | 19 | 2024–07–22 00:32:54 | | **Card number** | Masked number of the card used to make the payment | 9–19 | 553691******0123 | | **paymentSessionMerchantMetadata** | Additional data you passed within the request for the operation | 6–20 | 1Di732vw57 | | **RRN** | string | Retrieval Reference Number: the unique identifier of a bank transaction (optional) | 12345678 | ### Payment types - Adjustment—partial cancellation of a transaction - Advice—successful transaction (one-time payments and payments within which a token is created) - Refund—rollback of a successful transaction - Compensation—refund. The total of such a payment can be negative if the total of Refund or Chargeback exceeds the total of Advice - Recurrent—recurring payment (transactions made with a token) --- ## Daily payouts report > Source: /docs/finance/payouts-daily-report The daily report is sent in the XLSX or CSV format to the email address specified in your agreement with Smart Glocal. To receive the reports in another way (for example, via SFTP), please contact your Account Manager. ## How to use the report The report sent by Smart Glocal contains a list of all successful operations for a day (24 hours). You need to check the operations on your side against those in the report. In case of any discrepancy, contact our support team. The timeframe for making corrections is specified in your agreement with Smart Glocal. ## Report file name _YYYY-MM-DD_YYYY-MM-DD ## Report fields | Field name | Format | Description | Example | |------------------------------------|------------------------------|------------------------------------------------------------------------------------|---------------------| | **operationId** | string | Smart Glocal's payment identifier | po_4728377 | | **transactionDate** | string (YYYY–MM–DD HH:MM:SS) | Time of payment creation on Smart Glocal's side | 2024–03–21 23:17:56 | | **finishedAt** | string (YYYY–MM–DD HH:MM:SS) | Time of payment completion on Smart Glocal's side | 2024–03–21 23:17:57 | | **typeOfPayment** | string | Transaction type. Options: Advice—a payout; Refund—a refund | Advice | | **paymentFast** | int | Payout type (always: 0) | 0 | | **paymentSessionId** | string | Payment session identifier | ps_3748383 | | **paymentSessionMerchantMetadata** | string | Additional data passed within the request | 330 | | **paymentMethodIdentity** | string | Payment instrument (bank account number, etc.) | 4242 4242 4242 4242 | | **product** | string | Product or service identifier according to the agreement with Smart Glocal | new_test_payouts | | **grossLocalAmount** | decimal | Total payout amount including the fee | 436 | | **paymentLocalAmount** | decimal | Payout amount without the fee | 430 | | **feesLocalAmount** | decimal | Smart Glocal's fee (grossLocalAmount - paymentLocalAmount) | 6 | | **Currency amount** | string | Transaction currency (ISO) (optional) | USD | | **Currency fee** | string | Fee currency (ISO) (optional) | USD | | **RRN** | string | Retrieval Reference Number: the unique identifier of a bank transaction (optional) | 12345678 | --- ## Objects and arrays > Source: /docs/reference/objects ## acquiring_payments = payment_list >Use acquiring_payments for API v1, and payment_list for API v2. All the payment details. | Name | Mandatory | Type | Description | | -------------------- | --------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | + | string | Unique payment identifier | | status | + | string | Payment status. Options: succeeded, in_progress, pending, failed | | created_at | + | string | Creation date in ISO 8601 format | | finished_at | - | string | Completion date in ISO 8601 format | | customer | - | object | [User (payer) details](/docs/reference/objects#customer) | | payment_details | + | object | [Payment data](/docs/reference/objects#payment_details) | | amount_details | + | object | [Amount](/docs/reference/objects#amount_details) | | recurrent | - | object | [Details needed to perform recurring payments](/docs/reference/objects#recurrent_info) | | items | - | object | [Purchased product/service details](/docs/reference/objects#items) | | participant_details | - | object | [Participant details](/docs/reference/objects#participant_details) | | refunds | - | array | [Refund list](/docs/reference/objects#refunds) | | customer_interaction | - | object | [Data needed for user interaction](/docs/reference/objects#customerinteraction) | | transaction_info | - | object | [Transaction information](/docs/reference/objects#transaction_info) | | metadata | - | object | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks. May contain string, integer, or JSON object data | | error | - | object | [Error description](/docs/reference/objects#error) | #### Payment statuses (status) - in_progress—the payment is being processed - pending—awaiting your confirmation ([session/confirm](/docs/reference/methods/session-confirm)) or cancelation ([session/cancel](/docs/reference/methods/session-cancel)) - succeeded—the payment has been completed successfully - failed—the payment has failed ## acquiring_widget Settings for the payout form widget (for performing bank card payments). | Name | Mandatory | Type | Description | | ----------------------- | --------- | ------ | ------------------ | | session_id | + | string | Payment session identifier | | locale | - | string | Localization parameter. Options: en, ru. Default value: en | | show_recurrent_checkbox | - | bool | Whether to display the **I agree to recurring payments** checkbox in the widget interface | | success_return_url | - | string | URL to which the user is redirected after the payment is successfully completed | | failure_return_url | - | string | URL to which the user is redirected if an error occurs during the payment | | success_on_hold | - | bool | Whether to show the message about a successful payment to a payer when holding. Default value: false (the widget shows the loading screen until the end of the hold) | | redirect_target | - | string | Redirect link open options: - top—outside of all the frames as the top window - self—in the same frame - parent—in the next-level frame if the frames are nested in one another. Default: top | ## actions Information about actions taken. | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------| | confirm | - | string | Confirmation date in ISO 8601 format | | capture | - | string | Capture date in ISO 8601 format | ## amount_details An amount object. | Name | Mandatory | Type | Description | | -------- | --------- | ------ | --------------------------------------------------------------------------------------------------------- | | amount | + | int | Amount in minor currency units (USD decimal format), i.e. if the value is 10000, the amount is 100 USD | | currency | + | string | ISO 4217 currency code. Case insensitive | ## bank_account Payout recipient's account description. | Name | Mandatory | Type | Description | | ------ | --------- | ------------------------------------------------------------------- | ---------------------------------------------------------- | | system_type | + | string | Bank payment system. Options: global, ru | | global | - (mandatory for type = global) | object | [Recipient's bank account details](/docs/reference/objects#bank_account_global) | | ru | - (mandatory for type = ru) | object | [Recipient's bank account details](/docs/reference/objects#bank_account_ru) | ## bank_card Unencrypted card details. | Name | Mandatory | Type | Description | | ---------------- | --------- | ------ | ------------------- | | number | + | string | Card number | | expiration_month | - (mandatory for payments if available) | string | Month | | expiration_year | - (mandatory for payments if available) | string | Year | | security_code | - (mandatory for payments if available) | string | CVC (security code) | | cardholder_name | - | string | Cardholder's name | ## card Payout recipient's bank card details. | Name | Mandatory | Type | Description | | -------------- | --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------ | | type | + (not returned in responses) | string | Card details transmission type. Options: bank_card, encrypted_card | | bank_card | - (mandatory for type = bank_card) | object | [Unencrypted card](/docs/reference/objects#bankcard) | | encrypted_card | - (mandatory for type = encrypted_card) | object | [Card with encrypted fields (tokenized)](/docs/reference/objects#encryptedcard) | | brand | - | string | Card information | | last4 | - | string | Card information | | bin | - | string | Bank Identification Number (BIN) (the first 6 digits of a card number) | | card_id | - | string | [Card identifier](/docs/payouts/payouts-intro#cross-identifier-card) | | country_iso3 | - | string | Country code (ISO-3166-1 alpha-3) | | bank_name\* | - | string | Name of the bank that issued the card | \* To start using the bank_name parameter, please contact your Account Manager. ## contacts Contacts of the user (payout recipient or payment sender). | Name | Mandatory | Type | Description | |---------|-----------|--------|---------------------| | email | - | string | User's email | | phone | - | string | User's phone number | ## country_ewallet Country information. | Name | Mandatory | Type | Description | |------|-----------|--------|------------------------------------------------| | country_iso2 | + | string | Country code (ISO-3166-1 alpha-2) | ## customer Data on the user (payout recipient or payment sender) in your system (e.g., the login that lets you identify the user). It also includes their contact details. | Name | Mandatory | Type | Description | | --------- | --------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------- | | reference | + | string | User's identifier (payout recipient or payment sender) in your system | | contacts | - | array | [User contacts](/docs/reference/objects#contacts) | ## customer_interaction Customer interaction details. | Name | Mandatory | Type | Description | | -------- | --------- | ------------------------ | ------------------------ | | type | + | string | Customer interaction type. Options: redirect, inform | | redirect | - (mandatory of type: redirect) | object | [User redirect data](/docs/reference/objects#redirect) | | inform | - (mandatory of type: inform) | object | [Payment method information](/docs/reference/objects#inform) | ## encrypted_card Card with encrypted fields (tokenized). Transmitted during payouts or payments through the widget. | Name | Mandatory | Type | Description | | -------------------- | --------- | ------ | ---------------------- | | number_hash | + | string | Card number hash | | expiration_date_hash | - | string | Expiration date hash | | security_code_hash | - | string | CVC code hash | | cardholder_name_hash | - | string | Cardholder's name hash | ## error Error details. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ----------------- | | code | + | string | Error code | | description | + | string | Error description | [Error codes](/docs/reference/errors) ## faster_payment_system FPS details for payouts and payments. | Name | Mandatory | Type | Description | | ---------------- | --------- | ------ | ------------------- | | phone | - (mandatory for payouts) | string | Recipient's phone number | | bank_id | - (mandatory for payouts) | string | Identifier of the recipient's bank in the FPS | | description | - (*) | string | Payout or payment purpose | >(*) To learn whether or not the description parameter is mandatory, contact your Account Manager. ## fps_no_account_widget Settings for the payment page for money transfers. | Name | Mandatory | Type | Description | | ------ | --------- | ------ | ------------------------------------------------------------------------------------- | | session_id | + | string | Payment session identifier | ## global (bank accounts) Bank account details (region: global). | Name | Mandatory | Type | Description | | ------------------- | --------- | ------ | ------------------------------------ | | bank_account_number | - | string | Bank account number | | account_type | - | string | Account type | | routing_code | - | string | Routing code | | swift_bic_code | - | string | SWIFT BIC code | | sort_code | - | string | Sort code | | msisdn | - | string | Phone number | | iban | - | string | IBAN | | description | - | string | Purpose of remittance for the payout | | bsb_number | - | string | BSB number | | ifs_code | - | string | IFS code | | branch_number | - | string | Branch number | > To learn which parameters are mandatory, check the information on a particular country. ## global (wallets) Wallet details. | Name | Mandatory | Type | Description | |--------------------------|-----------|---------------------|-------------------------------------------------------| | name | + | string | Wallet name | | msisdn | + | string | Phone number | | description | + | string | Purpose of remittance for the payout | ## identity_document Identity details. | Name | Mandatory | Type | Description | | ------------------ | --------- | ------ | ------------------------ | | id_type | - | string | Identity type | | id_number | + | string | Identity number | | id_expiration_date | - | string | Identity expiration date | ## info (card token information) Details of a tokenized bank card. | Name | Mandatory | Type | Description | |--------------|-----------|--------|-------------------------------------------------| | number_hash | + | string | Token (tokenized bank card) | | brand | + | string | Payment system, i.e. visa | | last4 | + | string | Last 4 card numbers | | country_iso3 | - | string | Country of the card's bank (ISO-3166-1 alpha-3) | | type | + | string | Token type. Always: card | ## info (public token information) Information on a public token. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ---------------------------------------------------------------------------------------- | | token | + | string | Token | | created_at | + | string | Creation date in ISO 8601 format | | finished_at | + | string | Completion date in ISO 8601 format | | is_active | + | bool | Whether the token can be used for an operation: true—yes, false—no | | type | + | string | Token type. Always: public_token | ## info (recurring transaction token information) Information on a token for recurring payments/payouts. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ---------------------------------------------------------------------------------------------------------------- | | token | + | string | Token | | created_at | + | string | Creation date in ISO 8601 format | | finished_at | + | string | Completion date in ISO 8601 format | | is_active | + | bool | Whether the token can be used for an operation: true—yes, false—no | | initiator | - | string | Recurring payment type. Options: merchant—an MIT payment (by default), client—a CIT payment | | type | + | string | Token type. Always: recurrent_token | ## inform Payment method details. | Name | Mandatory | Type | Description | |----------|-----------|---------------------|-------------------------------------------------------| | qr | - | object | [QR code for FPS payments](/docs/reference/objects#inform_qr) | ## internet_banking Payment details. | Name | Mandatory | Type | Description | |------|-----------|--------|------------------------------------------------| | type | + | string | Payment method. Options: pix, country_ewallet | | pix | - (mandatory for type = pix) | object | [Payer's details](/docs/reference/objects#pix) | | country_ewallet | - (mandatory for type = country_ewallet) | object | [Country information](/docs/reference/objects#country_ewallet) | ## items Details of each purchased product/service. | Name | Mandatory | Type | Description | |------------------------|-----------|--------|-----------------------------------------------------------------| | id | + |string | Product UUID in your system | | name | + | string | Product name | | amount_details | + | object | [Amount details](/docs/reference/objects#amount_details) | | | quantity | + | int | Quantity of product items | | category_code | + | string | Product item category. Always: general | ## participant_details Transaction participant details. | Name | Mandatory | Type | Description | | --------- | --------- | ------------------------------------------------------ | ------------------- | | recipient | - | object | [Recipient details](/docs/reference/objects#recipient) | | sender | - | object | [Sender details](/docs/reference/objects#sender) | ## payments = payout_list >Use payments for API v1, and payout_list for API v2. All the payout details. | Name | Mandatory | Type | Description | | ------------------- | --------- | -------------------------------------------------------------------- | ------------- | | id | + | string | Payout identifier | | status | + | string | Status. Options: succeeded, in_progress, pending, failed | | created_at | + | string | Creation date in ISO 8601 format | | finished_at | - | string | Completion date in ISO 8601 format | | customer | - | object | [Recipient data in your system](/docs/reference/objects#customer) | | payment_method/payout_details | + | object | [Method of receiving the payout](/docs/reference/objects#payment_method) | | amount_details | + | object | [Amount](/docs/reference/objects#amount_details) | | participant_details | - | object | [Details of the payout participants](/docs/reference/objects#participant_details) required to perform the payout | | refunds | - | array | [Refund list](/docs/reference/objects#refunds) | | transaction_info | - | object | [Transaction information](/docs/reference/objects#transaction_info) | | metadata | - | object | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks. May contain string, integer, or JSON object data | | error | - | object | [Error description](/docs/reference/objects#error) | #### Payout statuses (status) - in_progress—the payout is being processed - pending—awaiting your confirmation ([session/confirm](/docs/reference/methods/session-confirm)) or cancelation ([session/cancel](/docs/reference/methods/session-cancel)) - succeeded—the payout has been completed successfully - failed—the payout has failed ## payment_details Payment method description. | Name | Mandatory | Type | Description | |-----------------------|--------------------------------------------------------|--------|-----------------------------------------------------------------------------------------| | type | + | string | Payment method type. Options: card, recurrent, faster_payment_system, internet_banking | | card | - (mandatory for type = card) | object | [Bank card details](/docs/reference/objects#card) | | recurrent | - (mandatory for type = recurrent) | object | [Details needed to perform recurring payments](/docs/reference/objects#recurrent_token) | | faster_payment_system | - (mandatory for type = faster_payment_system) | object | [FPS details](/docs/reference/objects#faster_payment_system) | | internet_banking | - (mandatory for type = internet_banking) | object | [Payment details](/docs/reference/objects#internet_banking) | | sender | - (mandatory for local payments in India) | object | [Sender details](/docs/reference/objects#sender) | ## payment_method = payout_details >Use payment_method for API v1, and payout_details for API v2. Payout method description. | Name | Mandatory | Type | Description | | ------------ | --------- | ------------------- | ------------------------------------------------------------------------ | | type | + | string | Type of the method for receiving the payout. Options: card, bank_account, wallet, recurrent | | card | - (mandatory for type = card) | object | [Recipient's bank card](/docs/reference/objects#card) | | bank_account | - (mandatory for type = bank_account) | object | [Recipient's bank account](/docs/reference/objects#bank_account) | | wallet | - (mandatory for type = wallet) | object | [Recipient's wallet details](/docs/reference/objects#wallet) | | recurrent | - (mandatory for type = recurrent) | object | [Token for recurring payouts](/docs/reference/objects#recurrent_token) | ## payment_options Parameters needed to perform a payment. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | --------------------------------------------- | | return_url | - | string | URL to which the user is redirected after the payment is performed **Mandatory for payments made without our payment widget** | | recurrent | - | bool | Whether the payment is to be performed using a saved token | | description | - | string | Any additional information to be displayed to the user during 3DS verification (if the field is supported by the payment provider) | | platform_details | - | object | [User device data](/docs/reference/objects#platform_details) | ## pix Payer's details. | Name | Mandatory | Type | Description | |----------|-----------|--------|--------------------------------------------------------------------------------------------| | name | + | string | Payer's name and surname | | email | + | string | Payer's email | | document | + | string | Payer's identifier. For individuals: CPF (11 digits), for legal entities: CNPJ (14 digits) | ## platform_details User device data. | Name | Mandatory | Type | Description | |---------|-----------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------| | type | + | string | User's device type. Options: desktop, mobile | | os | + | string | User's operating system. Options: ios, android, windows, linux | | browser | + | string | User's browser. Options: chrome, firefox, jivoMobile, microsoft edge, miui, opera, safari, samsung, webKit, weChat, yandex | ## public_token Public token. | Name | Mandatory | Type | Description | | ----- | --------- | ------ | ----------- | | token | + | string | Token | ## qr QR code for FPS payments. | Name | Mandatory | Type | Description | | -------- | -------------- | ------ | ------------------ | | content | + | string | QR code link | | img | + | string | QR code image | ## recipient Payout recipient details. Which details are necessary depends on the method of receiving the payout. | Name | Mandatory | Type | Description | |-----------------------|-----------|--------|------------------------------------------------------------------------| | full_name | - | string | Full name | | first_name | - | string | First name | | last_name | - | string | Last name | | middle_name | - | string | Patronymic | | company_name | - | string | Company name | | reference | - | string | Recipient identifier in your system | | tax_reference | - | string | Taxpayer identifier | | address_line | - | string | Address | | ipv4 | - | string | IP version 4 address | | ipv6 | - | string | IP version 6 address | | country_iso3 | - | string | Country code (ISO-3166-1 alpha-3) | | country_iso2 | - | string | Country code (ISO-3166-1 alpha-2) | | city | - | string | City | | state | - | string | State | | postal_code | - | string | Postal code | | street | - | string | Street name | | identity_document | - | object | [Identity document details](/docs/reference/objects#identity_document) | | bank_name | - | string | Bank name | | currency | - | string | Currency (ISO 4217) | | registration_number | - | string | Company registration number | | code | - | string | Company registration number | | date_of_incorporation | - | string | Company incorporation date | | id_number | - | string | Identification number | | msisdn | - | string | Mobile wallet address | | email | - | string | Email address | ## recurrent (recurring transaction token details) Information on a token for recurring payments/payouts. | Name | Mandatory | Type | Description | |-------------|-----------|--------|-------------------------------------------------------------------------------------------------| | token | + | string | Token | | created_at | + | string | Creation date in ISO 8601 format | | finished_at | + | string | Completion date in ISO 8601 format | | is_active | + | bool | Whether the token can be used for an operation: true—yes, false—no | | initiator | - | string | Recurring payment type. Options: merchant—an MIT payment (by default), client—a CIT payment | | type | + | string | Token type. Always: recurrent_token | ## recurrent (recurring transaction token) Token for recurring payments/payouts. | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------------------------------------------------| | token | + | string | Token | | initiator | - | string | Recurring payment type. Options: merchant—an MIT payment (by default), client—a CIT payment | ## recurrent_token Token for recurring payments or payouts. | Name | Mandatory | Type | Description | | ----- | --------- | ------ | ----------- | | token | + | string | Token | ## redirect User redirect data. | Name | Mandatory | Type | Description | | -------- | --------- | ----------------------- | ----------------------------------------------------- | | url | + | string | Redirect address including GET parameters | | base_url | + | string | Redirect address | | method | + | string | Submission method. Options: POST, GET | | qs | - | map\ | A set of parameters depending on the transaction method | | params | - | map\ | A set of parameters depending on the transaction method | >- Check if any parameters are specified in the qs and params objects. >- Redirect the user to the redirect address specified in base_url using the method from the method parameter and including all the required parameters in the URL or request body. ## refunds Refund details. | Name | Mandatory | Type | Description | |--------------------|----------------------------------------------------------------------------------------|--------|------------------------------------------------------------------------------------------------------------| | id | + | string | Unique refund identifier | | status | + | string | Refund status. Options: in_progress, accepted, declined, error | | amount_details | + | object | [Refund amount details](/docs/reference/objects#amount_details) | | created_at | + | string | Creation date | | finished_at | - | string | Completion date | | is_chargeback | - | bool | Whether the refund is made within a chargeback | | transaction_info | - | object | [Transaction information](/docs/reference/objects#transaction_info) | | metadata | - | object | Additional information | #### Refund statuses (status) - in_progress—the refund is being processed - accepted—the refund has been completed successfully - declined—Smart Glocal has declined the refund - error—the refund has failed ## ru Bank account details (region: ru). | Name | Mandatory | Type | Description | | ----------- | ----------------- | ------ | ------------------------------- | | bik | + | string | Recipient’s Bank Identification Code | | account | + | string | Recipient's bank account | | full_name | + | string | Individual's full name. In case of a payout to an account of a sole proprietor should be passed in the following format: ИП <full name>. In case of a payout to a legal entity, enter the entity's name, if it is provided in the agreement. Important: if the name is passed incorrectly the recipient bank may cancel the payout and the payout will be refunded | | description | + | string | Payout purpose | | inn | - (mandatory for payouts to the accounts of legal entities and individual proprietors) | string | Recipient's INN, 10 digits for legal entities, 12 digits for individuals, including individual proprietors | | kpp | - (mandatory for payouts to the accounts of legal entities) | string | Recipient's Tax Registration Reason Code (KPP) | | is_fast | - | bool | Whether it is a speedy payout (via BESP) | ## sender Payout payer details. Which details are necessary depends on the method of receiving the payout. | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|------------------------------------------------------------------------| | full_name | - | string | Full name | | first_name | - | string | First name | | last_name | - | string | Last name | | middle_name | - | string | Patronymic | | company_name | - | string | Company name | | reference | - | string | Recipient identifier in your system | | date_of_birth | - | string | Date of birth in the YYYY-MM-DD format | | tax_reference | - | string | Taxpayer identifier | | address_line | - | string | Address | | ipv4 | - | string | IP version 4 address | | ipv6 | - | string | IP version 6 address | | country_iso3 | - | string | Country code (ISO-3166-1 alpha-3) | | country_iso2 | - | string | Country code (ISO-3166-1 alpha-2) | | city | - | string | City | | state | - | string | State | | postal_code | - | string | Postal code | | street | - | string | Street name | | building | - | string | Building number | | bank_name | - | string | Bank name | | currency | - | string | Currency (ISO 4217) | | registration_number | - | string | Company registration number | | code | - | string | Company registration number | | date_of_incorporation | - | string | Company incorporation date | | id_number | - | string | Identification number | | msisdn | - | string | Mobile wallet address | | email | - | string | Email address | | identity_document | - | object | [Identity document details](/docs/reference/objects#identity_document) | | document | - | string | Document number | | bank_name | - | string | Bank name | | currency | - | string | Currency (ISO 4217) | | registration_number | - | string | Company registration number | | code | - | string | Company registration number | | date_of_incorporation | - | string | Company incorporation date | | id_number | - | string | Identification number | | msisdn | - | string | Mobile wallet address | | email | - | string | Email address | ## session A container with data about all the operations performed within a single payment session. Payment operations can only be performed within a session. One or more operations of the same or different types can be performed within the session (e.g., several payouts, a payment and a refund, or a payment which is subsequently split). | Name | Mandatory | Type | Description | | ------------------ | --------- | ------------------ | ------------------------------------------------------------------ | | id | + | string | Session identifier | | status | + | string | Status. Options: created, in_progress, accepted, cancelled, error | | created_at | + | string | Creation date in ISO 8601 format | | updated_at | + | string | Update date in ISO 8601 format | | payments/payout_list | - | array | [Payouts performed within the session](/docs/reference/objects#payment) | | acquiring_payments/payment_list | - | array | [Payments performed within the session](/docs/reference/objects#acquiring_payment) | | next_action | - | string | Further required actions. Options: confirm, capture | | error | - | object | [Error description](/docs/reference/objects#error) | #### Payment session statuses (status) - created—the session has been created and is waiting to be started or canceled - in_progress—the payment is being processed - accepted—the payment has been completed successfully - cancelled—the payment has been canceled - error—an unexpected error occurred while processing > Attention! This status is not final. Please contact Smart Glocal's support team and wait for a final transaction status. #### Next steps (next_action) If this field is not empty, it means that Smart Glocal is waiting for you to perform specific actions to proceed with the operation: - confirm—confirm the operation ([session/confirm](/docs/reference/methods/session-confirm)) or cancel it ([session/cancel](/docs/reference/methods/session-cancel)) - capture—debit the money ([session/capture](/docs/reference/methods/session-capture)) or cancel the operation ([session/cancel](/docs/reference/methods/session-cancel)) ## tokenize_widget Settings for the tokenization widget. | Name | Mandatory | Type | Description | | ------ | --------- | ------ | ------------------------------------------------------------------------------------- | | access | + | bool | Identifies whether this public key can use the tokenization widget | | locale | - | string | Localization parameter. Options: en, ru. Default value: en | ## transaction_info | Name | Mandatory | Type | Description | |---------------|-----------|--------|-----------------------------------------------------------------------------------| | rrn | - | string | Retrieval Reference Number (a unique identifier generated for a bank transaction) | | arn | - | string | Acquirer Reference Number (a unique number assigned to credit card transactions) | | auth_code | - | string | Authorization code | | fp_message_id | - | string | Unique transaction identifier in FPS | ## wallet Recipient's wallet details. | Name | Mandatory | Type | Description | |----------------|-----------|---------------------|---------------------------| | type | + | string | Options: global | | global | + | object | [Wallet details](/docs/reference/objects#wallet_global) | ## wallets Details on the wallet balance used to make payouts. | Name | Mandatory | Type | Description | | -------------- | --------- | --------------------------------------------------------------- | ------------------ | | id | + | string | Balance identifier | | amount_details | + | object | [Current balance](/docs/reference/objects#amount_details) | --- ## Error codes > Source: /docs/reference/errors > The error codes may be changed without prior notice. | Name | Description | | ------------------------------------ | ---------------------------------------------------------------- | | 3DS_error | For a successful transaction, authorization (3DS or another method) is required | | activity_count_exceeded | The activity/amount limit for the card/wallet is exceeded | | authentication_error | An authentication error occurred | | authorization_error | An authorization error occurred | | bank_card_expired | The bank card is past its expiration date | | cancelled_by_customer | The transaction was canceled by the customer | | capture_timeout | The transaction was canceled as the confirmation timeout expired | | card_number_does_not_exist | The provided card number is invalid | | confirm_timeout | The confirmation timeout expired, the transaction was canceled | | declined_by_issuer_bank | The operation was declined by the emitting bank | | idempotency_key_already_exists | The previous request with the same key is still in progress. Wait till the previous request is processed | | idempotency_key_not_supported | This method cannot be used with an idempotency key | | idempotency_key_params_mismatch | The key has already been used for another session. Use another idempotency key | | identification_error | A partner identification error occurred | | incomplete_data | Some data is missing in the request. Please check your request for correctness | | incorrect_card_data | The provided card details are incorrect | | insufficient_funds | The card does not have enough funds | | insufficient_wallet_balance | The balance is not enough. The error is returned when you try to make a payout if your [prefunding balance](/docs/payouts/payouts-intro#prices-and-preconditions) is not enough | | internal_error | An internal error occurred | | invalid_details | The transaction parameters are in the wrong format | | invalid_request | The request is invalid | | invalid_recipient_details | The recipient details are invalid | | invalid_sender_details | The sender details are invalid | | invalid_transaction | The transaction is invalid | | issuer_bank_fault | An error occurred on the issuer bank's side | | not_permitted_by_issuer_bank | The operation is not permitted by the emitting bank | | not_permitted_to_card | The transaction is not permitted for the card holder | | operation_rejected | The operation was rejected for security reasons | | provider_exceeds_amount_limit | The amount limit for the provider was exceeded | | provider_foreign_transfer_prohibited | A transfer to a foreign/corporate card for this provider is not allowed | | provider_internal_error | A provider error | | provider_issuer_unavailable | The provider issuer is unavailable | | provider_timeout | The provider timeout expired | | qr_expired | The QR code has expired | | refund_amount_too_large | The refund amount exceeds the maximum allowed amount | | routing_internal_error | A payment condition determination error occurred | | session_cancelled | The session was canceled | | session_cancelled_by_partner | The session was canceled by the partner | | session_wrong_state | A transaction cannot be performed in this session status | | suspected_fraud | The transaction is suspicious | | wallet_internal_error | An error occurred while dealing with the balance | --- ## Webhooks > Source: /docs/reference/webhooks Our webhooks are notifications about events happening on Smart Glocal's side. Smart Glocal sends webhooks to inform you of the results of your operations, ask for confirmation, or alert you about actions you need to take. ## How to get webhooks You can decide whether you want to receive webhooks or not. >In case you decide to work without our webhooks, you will need to use the [session/status](/docs/reference/methods/session-status) method to understand your next step and the operation results. To **activate** the webhooks: 1. In your system, create an address at which you want to receive the webhooks. 2. Inform your Account Manager of this address. To **stop using** the webhooks, inform your Account Manager of your decision. ## What to send in response You are expected to send the 200 HTTP code in response to any webhook. If Smart Glocal receives a 4\*\* or 5\*\* code or no response, Smart Glocal will resend the webhook as follows: - the webhook will be resent repeatedly at intervals of increasing length (up to 15 minutes) - after 30 minutes Smart Glocal will stop resending the webhook :::info[] The webhook response may include additional fields, depending on the payment methods used. Your system must be able to process such fields without errors. ::: ## Available webhooks - [action_required](/docs/reference/webhooks/action-required) - [ready_to_capture](/docs/reference/webhooks/ready-to-capture) - [ready_to_confirm](/docs/reference/webhooks/ready-to-confirm) - [payment_finished](/docs/reference/webhooks/payment-finished) - [payment_refunded](/docs/reference/webhooks/payment-refunded) --- ## action_required > Source: /docs/reference/webhooks/action-required ## action_required Smart Glocal sends you this webhook when you or your users need to carry out certain actions to proceed with the operation. For example, the user might need to go through 3D Secure authentication when paying via a bank card. >The maximum waiting time for an action is 60 minutes. If the action does not occur within this time, the operation will automatically be terminated with the canceled status. ### Parameters | Name | Mandatory | Type | Description | | ------- | --------- | ------------------------------------------------------------ | -------------------------------------- | | type | + | string | Webhook type: action_required | | session | + | object | [Payment session](/docs/reference/objects#payment_session) | ### Example --- ## payment_finished > Source: /docs/reference/webhooks/payment-finished ## payment_finished You receive this webhook when Smart Glocal has completed an operation. The webhook body contains all the details of the operation, including its final status (in the status field). For example, if you are sending a payout and have received the succeeded status in this webhook, it means that the payout has been completed successfully. :::warning[] If the payment/payout status is failed and the session status is error, do not immediately attempt to retry the transaction, as the error status is not final. Instead contact Smart Glocal support to confirm the final status. ::: ### Parameters | Name | Mandatory | Type | Description | | ------- | --------- | ------------------------------------------------------------ | --------------------------------------- | | type | + | string | Webhook type: payment_finished | | session | + | object | [Payment session](/docs/reference/objects#payment_session) | ### Example --- ## payment_refunded > Source: /docs/reference/webhooks/payment-refunded ## payment_refunded Smart Glocal sends you this webhook after performing a refund. It contains information on the payment session, including all the details about the refund. If the refund was made as part of the chargeback procedure, the refunds array will contain "is_chargeback": true. ### Parameters | Name | Mandatory | Type | Description | | ------- | --------- | ------------------------------------------------------------ | --------------------------------------- | | type | + | string | Webhook type: payment_refunded | | session | + | object | [Payment session](/docs/reference/objects#payment_session) | ### Example --- ## ready_to_capture > Source: /docs/reference/webhooks/ready-to-capture ## ready_to_capture Smart Glocal sends you this webhook after placing a hold on money in case of delayed capture payments. To debit the money, send a [session/capture](/docs/reference/methods/session-capture) request. To cancel the payment, send a [session/cancel](/docs/reference/methods/session-cancel) request. ### Parameters | Name | Mandatory | Type | Description | | ------- | --------- | ------------------------------------------------------------ | --------------------------------------- | | type | + | string | Webhook type: ready_to_capture | | session | + | object | [Payment session](/docs/reference/objects#payment_session) | ### Example --- ## ready_to_confirm > Source: /docs/reference/webhooks/ready-to-confirm ## ready_to_confirm You receive this webhook when Smart Glocal is ready to perform an operation. You need to check the operation parameters and either confirm the operation by sending a [session/confirm](/docs/reference/methods/session-confirm) request or cancel the operation by sending a [session/cancel](/docs/reference/methods/session-cancel) request to Smart Glocal. >The maximum waiting time for a confirmation is 240 minutes. If no confirmation is received within this time, the operation will automatically be terminated with the canceled status. :::info[] For your convenience, you can use automatic payment session confirmation: in this case, you do not get a ready_to_confirm webhook and do not have to confirm the operation. To set up the automatic payment session confirmation, apply to your Account Manager. ::: ### Parameters | Name | Mandatory | Type | Description | | ------- | --------- | ------------------------------------------------------------ | --------------------------------------- | | type | + | string | Webhook type: ready_to_confirm | | session | + | object | [Payment session](/docs/reference/objects#payment_session) | ### Example --- ## "recurrent/disable" > Source: /docs/reference/methods/recurrent-disable ## recurrent/disable Use this request to disable a token. Pass the token in the request, in the response you will get is_active: false. This means the token has been disabled, you cannot perform recurring payments/payouts with this token any longer. ### Endpoint api/v1/recurrent/disable ### Request parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------| | recurrent | + | object | [Token](/docs/reference/objects#recurrent_token) | Request example ### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-----------------------------------------------------| | status | + | string | Status. Options: error, ok | | recurrent | + | object | [Token data](/docs/reference/objects#recurrent_info) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example --- ## "session/cancel" > Source: /docs/reference/methods/session-cancel ## session/cancel Send this request in response to a [ready_to_confirm](/docs/reference/webhooks/ready-to-confirm) or [ready_to_capture](/docs/reference/webhooks/ready-to-capture) webhook when you want to cancel the operation. ### Endpoint api/v1/session/cancel ### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | ------------------ | | session_id | + | string | Session identifier | Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example ### Endpoint api/v2/session/cancel ### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | ------------------ | | session_id | + | string | Session identifier | Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example --- ## "session/capture" > Source: /docs/reference/methods/session-capture ## session/capture Send this request after you received a [ready_to_capture](/docs/reference/webhooks/ready-to-capture) webhook when you are ready to debit the [amount put on hold](/docs/payments/payment-capture). To cancel the debit, send a [session/cancel](/docs/reference/methods/session-cancel) request. ### Endpoint api/v1/session/capture ### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | ------------------ | | session_id | + | string | Session identifier | Request example ### Response parameters | Name | Mandatory | Type | Description | | ------- | --------- | ------------------------------------------------------------ | ------------------------------------------------- | | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example ### Endpoint api/v2/session/capture ### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | ------------------ | | session_id | + | string | Session identifier | Request example ### Response parameters | Name | Mandatory | Type | Description | | ------- | --------- | ------------------------------------------------------------ | ------------------------------------------------- | | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example --- ## "session/confirm" > Source: /docs/reference/methods/session-confirm ## session/confirm Send this request after you receive a [ready_to_confirm](/docs/reference/webhooks/ready-to-confirm) webhook when you are ready to confirm the operation. ### Endpoint api/v1/session/confirm ### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | ------------------ | | session_id | + | string | Session identifier | Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example ### Endpoint api/v2/session/confirm ### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | ------------------ | | session_id | + | string | Session identifier | Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example --- ## "session/create" > Source: /docs/reference/methods/session-create ## session/create Send this request to create a payment session on Smart Glocal's side. >Payment operations can only be performed within a session. One or more operations of the same or different types can be performed within a session (e.g. several payouts, a payment and a refund, or a payment which is subsequently split). Use this request if you need to request data necessary to perform a payout or a payment from the user. For example, call the tokenization widget, show it to the user and get tokenized card details, and then send the payout request with those details. If you are ready to pass the payout/payment parameters right away, you can do so: For payments, pass payment_details, amount_details, and customer. For payouts, pass payment_method/payout_details and amount_details. The response contains the parameters of a session created. ### Endpoint api/v1/session/create ### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | payment_method | - | object | [Payout details](/docs/reference/objects#payment_method) | | payment_details | - | object | [Payment details](/docs/reference/objects#payment_details) | | amount_details | - | object | [Amount](/docs/reference/objects#amount_details) in the USD decimal format. To send 100 USD, specify 10000 | | participant_details | - | object | [Information on the sender and recipient](/docs/reference/objects#participant_details) | | customer | - | object | [Recipient's data in your system](/docs/reference/objects#customer) | | payment_options | - | object | [Additional payment parameters](/docs/reference/objects#payment_options) | | metadata | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | >If you do not specify payment_method and amount_details for payouts/payment_details, customer, and amount_details for payments in this request, make sure you specify them in your [session/start/payment](/docs/reference/methods/session-start-payment) or [session/start/payout](/docs/reference/methods/session-start-payout) request, respectively. Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example ### Endpoint api/v2/session/create ### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | payout_details | - | object | [Payout details](/docs/reference/objects#payment_method) | | payment_details | - | object | [Payment details](/docs/reference/objects#payment_details) | | amount_details | - | object | [Amount](/docs/reference/objects#amount_details) in the USD decimal format. To send 100 USD, specify 10000 | | participant_details | - | object | [Information on the sender and recipient](/docs/reference/objects#participant_details) | | customer | - | object | [Recipient's data in your system](/docs/reference/objects#customer) | | payment_options | - | object | [Additional payment parameters](/docs/reference/objects#payment_options) | | metadata | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | >If you do not specify payout_details and amount_details for payouts/payment_details, customer, and amount_details for payments in this request, make sure you specify them in your [session/start/payment](/docs/reference/methods/session-start-payment) or [session/start/payout](/docs/reference/methods/session-start-payout) request, respectively. Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example --- ## "session/init/payment" > Source: /docs/reference/methods/session-init-payment ## session/init/payment Send this request to simultaneously create a payment session and start a payment. The response contains the parameters of a session created and information on the payment ([acquiring_payments/payment_list](/docs/reference/objects#acquiring_payment)). >If you decide to use this method, please use an [idempotency key](/docs/reference/format#idempotency-key). ### Endpoint api/v1/session/init/payment ### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------| | payment_details | + | object | [Payment data](/docs/reference/objects#payment_details) | | amount_details | + | object | [Amount](/docs/reference/objects#amount_details) in the USD decimal format. To send 100 USD, specify 10000 | | items | - | object | [Purchased product/service details](/docs/reference/objects#items) | | participant_details | - | object | [Information on the sender and recipient](/docs/reference/objects#participant_details) | | customer | + | object | [Recipient's data in your system](/docs/reference/objects#customer) | | payment_options | - | object | [Additional payment parameters](/docs/reference/objects#payment_options) | | metadata | - | \* | Any additional information. If the transaction is processed by a submerchant, please specify the payment site: "metadata" {"merchant": leave_it_blank,"submerchant": "https ://website"} | Request example ### Response parameters | Name | Mandatory | Type | Description | | ------- | --------- | ------------------------------------------------------------ | ------------------------------------------------- | | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example ### Endpoint api/v2/session/init/payment ### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------| | payment_details | + | object | [Payment data](/docs/reference/objects#payment_details) | | amount_details | + | object | [Amount](/docs/reference/objects#amount_details) in the USD decimal format. To send 100 USD, specify 10000 | | participant_details | - | object | [Information on the sender and recipient](/docs/reference/objects#participant_details) | | customer | + | object | [Recipient's data in your system](/docs/reference/objects#customer) | | payment_options | - | object | [Additional payment parameters](/docs/reference/objects#payment_options) | | metadata | - | \* | Any additional information. If the transaction is processed by a submerchant, please specify the payment site: "metadata" {"merchant": leave_it_blank,"submerchant": "https ://website"} | Request example ### Response parameters | Name | Mandatory | Type | Description | | ------- | --------- | ------------------------------------------------------------ | ------------------------------------------------- | | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example --- ## "session/init/payout" > Source: /docs/reference/methods/session-init-payout ## session/init/payout Use this request to simultaneously create a session and start a payout. The response contains the parameters of a session created and information on the payout ([payments/payout_list](/docs/reference/objects#payment)). >If you decide to use this method, please use an [idempotency key](/docs/reference/format#idempotency-key). ### Endpoint api/v1/session/init/payout ### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------| | payment_method | + | object | [Payout data](/docs/reference/objects#payment_method) | | amount_details | + | object | [Amount](/docs/reference/objects#amount_details). Transmitted in the USD decimal format. To send 100 USD, you will need to specify 10000 | | participant_details | - | object | [Information on the sender and recipient](/docs/reference/objects#participant_details) | | customer | - | object | [Recipient's data in your system](/docs/reference/objects#customer) | | metadata | - | \* | Any additional information. If the transaction is processed by a submerchant, please specify the payment site: "metadata" {"merchant": leave_it_blank,"submerchant": "https ://website"} | Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example ### Endpoint api/v2/session/init/payout ### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------| | payout_details | + | object | [Payout data](/docs/reference/objects#payment_method) | | amount_details | + | object | [Amount](/docs/reference/objects#amount_details). Transmitted in the USD decimal format. To send 100 USD, you will need to specify 10000 | | participant_details | - | object | [Information on the sender and recipient](/docs/reference/objects#participant_details) | | customer | - | object | [Recipient's data in your system](/docs/reference/objects#customer) | | metadata | - | \* | Any additional information. If the transaction is processed by a submerchant, please specify the payment site: "metadata" {"merchant": leave_it_blank,"submerchant": "https ://website"} | Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example --- ## "session/refund" > Source: /docs/reference/methods/session-refund ## session/refund Use this request to return money to the user after a successful payment. After completing the refund, Smart Glocal will send you a [payment_refunded](/docs/reference/webhooks/payment-refunded) webhook. ### Endpoint api/v1/session/refund ### Request parameters | Name | Mandatory | Type | Description | |----------------|-----------|--------|---------------------------------------------------------------------------------------------------------------------------------------------| | session_id | + | string | Identifier of the session with the successful payment that needs to be refunded | | amount_details | - | object | [Amount of the refund](/docs/reference/objects#amount_details). If not specified, the refund will be made for the full amount of the payment | | metadata | - | \* | Additional information | Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example ### Endpoint api/v2/session/refund ### Request parameters | Name | Mandatory | Type | Description | |----------------|-----------|--------|---------------------------------------------------------------------------------------------------------------------------------------------| | session_id | + | string | Identifier of the session with the successful payment that needs to be refunded | | amount_details | - | object | [Amount of the refund](/docs/reference/objects#amount_details). If not specified, the refund will be made for the full amount of the payment | | metadata | - | \* | Additional information | Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example --- ## "session/start/payment" > Source: /docs/reference/methods/session-start-payment ## session/start/payment Send this request to start a payment within an existing session. In the parameters, pass the data necessary to perform a payment or change any pieces of data already passed. ### Endpoint api/v1/session/start/payment ### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-----------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | session_id | + | string | Payment session identifier | | payment_details | - | object | [Payment data](/docs/reference/objects#payment_details) | | amount_details | - | object | [Amount](/docs/reference/objects#amount_details) in the USD decimal format. To send 100 USD, specify 10000 | | items | - | object | [Purchased product/service details](/docs/reference/objects#items) | | customer | - | object | [Recipient's data in your system](/docs/reference/objects#customer) | | participant_details | - | object | [Information on the sender and recipient](/docs/reference/objects#participant_details) | | payment_options | - | object | [Additional payment parameters](/docs/reference/objects#payment_options) | | metadata | - | \* | Any additional information. If the transaction is processed by a submerchant, please specify the payment site: "metadata" {"merchant": leave_it_blank,"submerchant": "https ://website"} | >If you did not specify payment_details, amount_details, and customer in your [session/create](/docs/reference/methods/session-create) request, make sure you specify them in this request, since in this case they are mandatory. Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example ### Endpoint api/v2/session/start/payment ### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------| | session_id | + | string | Payment session identifier | | payment_details | - | object | [Payment data](/docs/reference/objects#payment_details) | | amount_details | - | object | [Amount](/docs/reference/objects#amount_details) in the USD decimal format. To send 100 USD, specify 10000 | | customer | - | object | [Recipient's data in your system](/docs/reference/objects#customer) | | participant_details | - | object | [Information on the sender and recipient](/docs/reference/objects#participant_details) | | payment_options | - | object | [Additional payment parameters](/docs/reference/objects#payment_options) | | metadata | - | \* | Any additional information. If the transaction is processed by a submerchant, please specify the payment site: "metadata" {"merchant": leave_it_blank,"submerchant": "https ://website"} | >If you did not specify payment_details, amount_details, and customer in your [session/create](/docs/reference/methods/session-create) request, make sure you specify them in this request, since in this case they are mandatory. Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example --- ## "session/start/payout" > Source: /docs/reference/methods/session-start-payout ## session/start/payout Send this request to start a payout within an existing session. In the parameters, pass the data necessary to perform a payout or change any pieces of data already passed. ### Endpoint api/v1/session/start/payout ### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------| | session_id | + | string | Payment session identifier | | payment_method | - | object | [Payout data](/docs/reference/objects#payment_method) | | amount_details | - | object | [Amount](/docs/reference/objects#amount_details). Transmitted in the USD decimal format. To send 100 USD, you will need to specify 10000 | | participant_details | - | object | [Information on the sender and recipient](/docs/reference/objects#participant_details) | | customer | - | object | [Recipient's data in your system](/docs/reference/objects#customer) | | metadata | - | \* | Any additional information. If the transaction is processed by a submerchant, please specify the payment site: "metadata" {"merchant": leave_it_blank,"submerchant": "https ://website"} | >If you did not specify payment_method and amount_details in your [session/create](/docs/reference/methods/session-create) request, make sure you specify them in this request, since in this case they are mandatory. Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example ### Endpoint api/v2/session/start/payout ### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------| | session_id | + | string | Payment session identifier | | payout_details | - | object | [Payout data](/docs/reference/objects#payment_method) | | amount_details | - | object | [Amount](/docs/reference/objects#amount_details). Transmitted in the USD decimal format. To send 100 USD, you will need to specify 10000 | | participant_details | - | object | [Information on the sender and recipient](/docs/reference/objects#participant_details) | | customer | - | object | [Recipient's data in your system](/docs/reference/objects#customer) | | metadata | - | \* | Any additional information. If the transaction is processed by a submerchant, please specify the payment site: "metadata" {"merchant": leave_it_blank,"submerchant": "https ://website"} | >If you did not specify payout_details and amount_details in your [session/create](/docs/reference/methods/session-create) request, make sure you specify them in this request, since in this case they are mandatory. Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example --- ## "session/status" > Source: /docs/reference/methods/session-status ## session/status Send this request if you want to get full information on a payment session. For example, you can check whether the payout was completed, or check if you are able to debit the amount put on hold during a card payment. The response contains all the details on all the operations performed within the payment session. ### Endpoint api/v1/session/status ### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | -------------------------- | | session_id | + | string | Payment session identifier | Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example ### Endpoint api/v2/session/status ### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | -------------------------- | | session_id | + | string | Payment session identifier | Request example ### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------| | status | + | string | Status. Options: error, ok | | session | - | object | [Payment session](/docs/reference/objects#payment_session) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example --- ## token > Source: /docs/reference/methods/token-method ## token Use this method to generate a public token to access Smart Glocal's JavaScript library and to work with the widgets. The token is valid for 24 hours. It can only be used for a single operation. ### Endpoint api/v1/token ### Request parameters | Name | Mandatory | Type | Description | | ---------------- | --------- | ------------------------------------------------------------------------------ | ---------------------------------------- | | tokenize_widget | - | object | [Data required by the tokenization widget](/docs/reference/objects#tokenizewidget) | | acquiring_widget | - | object | [Data required by the payment form widget](/docs/reference/objects#acquiringwidget) | | fps_no_account_widget | - | object | [Data required by the payment form for money transfers](/docs/reference/objects#fps_no_account_widget) | Request examples Get a token for the tokenization widget. Get a token for the payment form widget. To get a token for the payment form widget with the recurring payments option, pass "show_recurrent_checkbox": "true". Get a token for the payment form for money transfers. ### Response parameters | Name | Mandatory | Type | Description | | ------------ | --------- | ------------------------------------------ | ------------------------------------------------- | | status | + | string | Status. Options: error, ok | | public_token | - | string | Public token | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example --- ## "token/info" > Source: /docs/reference/methods/token-info ## token/info Operations with bank cards are often carried out with tokenized values. For payouts and payments through widgets, a public token is created. A token can also be created for recurring payments/payouts. Use this method to learn the hidden card number and show the user from which card the funds will be debited, or to check the token expiration date. ### Endpoint api/v1/token/info ### Request parameters | Name | Mandatory | Type | Description | |-----------------|-------------------------------------------------|--------|----------------------------------------------------------------------------| | type | + | string | Request type. Options: card, public_token, recurrent_token | | card | - (mandatory for type = card) | object | [Bank card details](/docs/reference/objects#card) | | public_token | - (mandatory for type = public_token) | object | [Public token details](/docs/reference/objects#publictoken) | | recurrent_token | - (mandatory for type = recurrent_token) | object | [Recurring payment token details](/docs/reference/objects#token_recurrent) | Request examples Send tokenized bank card details to get the hidden card number and payment system. Send a public token to get information about it. Send a token for recurring payments/payouts to get information about it. ### Response parameters | Name | Mandatory | Type | Description | |--------|-----------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | status | + | string | Status. Options: error, ok | | info | - | object | Depending on the request type (type): - [card token information](/docs/reference/objects#card_token_info)- [public token information](/docs/reference/objects#public_token_info)- [information on the token for recurring payments](/docs/reference/objects#recurrent_token_info) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response examples Unsuccessful response example --- ## "wallet/balance" > Source: /docs/reference/methods/wallet-balance ## wallet/balance If you have wallets used for payouts, use this request to check your current Smart Glocal deposit balance. >The amount is returned in minor currency units (USD decimal format). If the value is 10000, the amount is 100 USD. ### Endpoint api/v1/wallet/balance ### Request parameters | Name | Mandatory | Type | Description | | ------------------- | --------- | ---------| ------------------ | | request_datetime | + | string | Timestamp of the request in ISO 8601 | Request example ### Response parameters | Name | Mandatory | Type | Description | | ------- | --------- | ------------------------------------------------------------ | ------------------------------------------------- | | status | + | string | Status. Options: error, ok | | wallets | - | object | [List of wallet accounts available in Smart Glocal](/docs/reference/objects#wallet_details) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example Unsuccessful response example --- ## Currency conversion payments > Source: /docs/payments/conversion With our payment widget, you can allow your users to make payments in a currency other than that specified for a service or item. The widget will show them the target amount calculated at the current exchange rate along with the period of time during which this rate is guaranteed. To enable this functionality, please contact your Account Manager. >You can set a single target currency for a project. The source currency can be any currency. ## Making a currency conversion payment For example, a user wants to make a payment in euros for a service that is priced in US dollars. 1. Create a session using the [session/create](/docs/reference/methods/session-create) method. In response, you will get the exchange_amounts object containing the source amount, target amount, and applied rate. Request example Response example 2. Send a [token](/docs/reference/methods/token-method) request to create a token using the returned session identifier and specifying the widget name. As a result you will receive a public token. Request example 3. Use the returned public token to initialize the widget. Example 4. To display the payment form, call the render() method: Example 5. Let the user interact with the widget through all the required steps. The user will see the target amount in the target currency and the time left to pay at the specified rate. ![new-Widget](/img/docs/payments/widget-time.png) If the user fails to pay within the specified time, an error will be displayed and the transaction will need to be restarted. ![new-Widget](/img/docs/payments/widget-error.png) 6. Wait for a [ready_to_confirm](/docs/reference/webhooks/ready-to-confirm) webhook. When you receive it, it means that Smart Glocal is ready to make the payment and is waiting for your confirmation. 7. Send a [session/confirm](/docs/reference/methods/session-confirm) request to confirm the operation or a [session/cancel](/docs/reference/methods/session-cancel) request to cancel it. 8. After the customer makes the payment, you will receive a [payment_finished](/docs/reference/webhooks/payment-finished) webhook containing the payment result from Smart Glocal. Webhook example --- ## Vietnam. Ewallet payments > Source: /docs/payments/country-ewallet You can make local ewallet payments in Vietnam in Vietnamese dongs (VND). >No recurring payments are available. ## Making a payment 1. Create a session using the [session/create](/docs/reference/methods/session-create) method. >Alternatively, you can use the [session/init/payment](/docs/reference/methods/session-init-payment) method. In this case, specify all the payment parameters right away and skip the next step. 2. Send a [session/start/payment](/docs/reference/methods/session-start-payment) request. Specify the following parameters: - country_ewallet in internet_banking.type - country_iso2 in internet_banking.country_ewallet - the payer's full name and document in participant_details.sender - the payer's email in customer.reference.contacts Optionally, you can add a return URL to redirect the customer back after the payment (payment_options.return_url). Request example Response example 3. Wait for a [ready_to_confirm](/docs/reference/webhooks/ready-to-confirm) webhook. When you receive it, it means that Smart Glocal is ready to make the payment and is waiting for your confirmation. Webhook example 4. Send a [session/confirm](/docs/reference/methods/session-confirm) request to confirm the operation or a [session/cancel](/docs/reference/methods/session-cancel) request to cancel it. Request example 5. Wait for an [action_required](/docs/reference/webhooks/action-required) webhook. The customer_interaction.redirect.url parameter contains a deeplink to a QR code. Webhook example 5.1 The user redirected by the link from the webhook lands on a page like this: ![](/img/docs/payments/ewallet/viet1.png) 5.2 The user selects a payment method and the QR code appears. ![](/img/docs/payments/ewallet/viet2.png) 5.3 After the user completes the payment, a message on successful payment appears. ![](/img/docs/payments/ewallet/viet3.png) 6. After the customer makes the payment, you will receive a [payment_finished](/docs/reference/webhooks/payment-finished) webhook containing the payment result from Smart Glocal. The succeeded status indicates a successful payment. Webhook example ### Sequence diagram of QR code payments ![](/img/docs/payments/ewallet.png) --- ## Instant bank-to-bank transfers in India > Source: /docs/payments/india-accounts You can use India'a Unified Payments Interface (UPI) to make instant bank-to-bank transfers via mobile apps using QR codes or UPI IDs without entering card details. Currency: **INR** and **USD** Minimum payment amount: **1 INR** To make a payment, complete the [standard steps](/docs/payments/one-time-payment). ### Mandatory parameters >Note that some parameters below are extra to those required for a standard payout. Please do not forget to get all the required sender data on your own. | Name | Type | Description | |---------------------------------------|--------|--------------------------------------------------------------------------------------------------------| | payment_details | object | [Payment data](/docs/reference/objects#payment_details) | |   type | string | Always: bank_account | |   bank_account | object | [Recipient's account description](/docs/reference/objects#bank_account) | |     system_type1 | string | Always: upi | |     upi | object | Always: {} | | participant_details | object | [Participant details](/docs/reference/objects#participant_details) | |   sender | object | [Sender details](/docs/reference/objects#sender) | |     full_name | string | Sender's full name (3–50 characters) | |     email | string | Sender's email address (up to 64 characters before @, the total length must not exceed 100 characters) | |     document | string | Document (up to 30 characters) | |     msisdn | string | Phone number (up to 15 characters, without + ) | |     state | string | Sender's state (up to 10 characters) | |     city | string | Sender's city (3–50 characters) | |     street | string | Sender's street (4–100 characters) | |     building | string | Building number | | amount_details | object | [Payment amount details](/docs/reference/objects#amount_details) | |   amount | int | Payout amount in decimal format. To send 100 USD, write 10000 | |   currency | string | ISO 4217 currency code. Case insensitive. Options: inr, usd | | metadata | object | Additional information | |   key | string | Metadata | | customer | object | [User details](/docs/reference/objects#customer) | |   reference | string | Sender reference identifier | ### Request example ### Screen examples After the action_required` webhook is received, the user will be redirected to the bank's/payment system's app to confirm the payment. Below is an example of the app interface. ![success](/img/docs/payments/app-screens.png) --- ## Parameters required in the MoR model > Source: /docs/payments/mor If you work with Smart Glocal according to the [Merchant of Record model](/docs/payments/payment-intro#mor), make sure you pass all the parameters required to calculate tax correctly and to send confirmations and receipts. To make a payment, complete the [standard steps](/docs/payments/one-time-payment). ## Required parameters The parameters listed below are not the complete set of fields you need to transmit. They represent only the required parameters necessary in the MoR model. [Check all the parameters](/docs/reference/methods/session-start-payment) | Name | Type | Description | |------------------------------------|--------|--------------------------------------------------------------------| | items | array | [Purchased product/service details](/docs/reference/objects#items) | |   id | string | Product UUID in your system | |   name | string | Product name | |   amount_details | object | [Amount details](/docs/reference/objects#amount_details) | |     amount | int | Amount | |     currency | string | ISO 4217 currency code. Case insensitive | |   quantity | int | Quantity of product items | |   category_code | string | Product item category. Always: general | | sender | object | [Sender details](/docs/reference/objects#sender) | |   country_iso3 | string | Payer's country | |   email | string | Payer's email address | |   postal_code | string | Payer's postal code (for the USA only) | #### Sample request --- ## Brazil. Pix payments > Source: /docs/payments/payment-pix To make local payments in Brazil, you can use Brazil's electronic payment system Pix. Such instantaneous payments can only be made in Brazilian real (BRL). If you specify any other currency, the amount will be automatically converted into BRL. >No recurring payments are available. ## Making a Pix payment 1. Create a session using the [session/create](/docs/reference/methods/session-create) method. >Alternatively, you can use the [session/init/payment](/docs/reference/methods/session-init-payment) method. In this case, specify all the payment parameters right away and skip the next step. 2. Send a [session/start/payment](/docs/reference/methods/session-start-payment) request. Specify the following parameters: - pix in internet_banking.type - the payer's name, email and CPF or CNPJ document in pix - country_iso2 in participant_details.sender Optionally, you can add a return URL to redirect the customer back after the payment (payment_options.return_url). Request example Response example 3. Wait for a [ready_to_confirm](/docs/reference/webhooks/ready-to-confirm) webhook. When you receive it, it means that Smart Glocal is ready to make the payment and is waiting for your confirmation. Webhook example 4. Send a [session/confirm](/docs/reference/methods/session-confirm) request to confirm the operation or a [session/cancel](/docs/reference/methods/session-cancel) request to cancel it. Request example 5. Wait for an [action_required](/docs/reference/webhooks/action-required) webhook. The customer_interaction.redirect.url parameter contains a deeplink to Pix QR. Webhook example 6. After the customer makes the payment, you will receive a [payment_finished](/docs/reference/webhooks/payment-finished) webhook containing the payment result from Smart Glocal. The succeeded status indicates a successful payment. Webhook example ### Sequence diagram of QR code payments ![](/img/docs/payments/pix.png) --- ## Performing payments with the widget > Source: /docs/widget/payment-widget You can use our payment form widget to perform payments. ## Getting started To start using our widget, do the following: ### Link the scripts and styles In test environment For real payments ### Add the widget container Once the script is linked to the page, the SmglPaymentForm class will appear in the global scope. Now, you can make payments using our widget. ### Validated information The following information is checked: - The card number is 14-18 digits long. - The validity period is a date. > The validity period is not checked for whether it is expired or not! - The CVC/CVV is 3 or 4 digits long and consists of digits only. - If some fields are incorrectly filled in, the customer will see it when they click the **Pay** button. ## Making a payment using the widget Below is an example of how to start any payment through the widget. Complete the following steps: 1. Create a new session every time a user clicks **Pay**. To do this, send a [session/create](/docs/reference/methods/session-create) request. :::info[] Check the [parameters](/docs/payments/params) you need to pass when accepting a payment from [these countries](/docs/payments/payment-intro#countries). ::: >To get a token for recurring payments, you can either use the checkbox from Step 2, or pass recurrent: true in the [payment_options](/docs/reference/objects#payment_options) object. 2. Send a [token](/docs/reference/methods/token-method) request to create a token using the returned session identifier and specifying the widget name. As a result you will receive a public token. > To create a widget with the **I agree to recurring payments** checkbox to get a token for recurring payments, pass true in the show_recurrent_checkbox parameter. Note that initially this checkbox can be either empty (by default) or preselected. If you prefer it to be preselected, please contact your Account Manager. Example > You can also pass the locale optional parameter to ensure the widget localization stays the same after the user is redirected by a provider for additional services (for example, 3D Secure). Currently, the following values are available: "locale":"en" and "locale":"ru". If this parameter is not passed, "locale":"en" is used. 3. Use the returned public token to initialize the widget. Example 4. To display the payment form, call the render() method: Example 5. Let the user interact with the widget through all the required steps. 6. Complete the operation according to the type of payment you are making. You will either receive webhooks or, if the webhooks are deactivated, you will need to check the session status to understand your next step as well as the payment result. > If, while using the widget, you receive an action_required webhook, send the HTTP 200 OK in response but do nothing, as the user will be redirected for 3D Secure within the widget. - [How to make a one-time payment using our widget](/docs/payments/one-time-payment) - [How to make a delayed capture payment using our widget](/docs/payments/payment-capture#how-to-make-a-delayed-capture-payment) - [How to start accepting recurring payments using our widget](/docs/payments/payment-recurring) ## Widget API ### SmglPaymentForm Payment form class constructor. | Parameter | Mandatory | Type | Description | | -------------------------------- | --------- | ----------- | ------------------------- | | publicToken | + | string | Public token | | options | - | object | Additional settings object | |   container | - | HTMLElement | Container into which the form will be inserted. Default value: | |  isCvcMasked | - | bool | Set this parameter to true to mask the **CVV/CVC** field value| |   hideCardHolderField | -| bool | Set this parameter to true to hide the **Cardholder** input field | |  customerInteractionRedirect | - | Object | Redirection details | |    target | - | string | 3DS window open options*:- _blank - in a new tab- _self- in the same frame- _parent - in the next level up of the frame if they are nested in one another- _top - outside of all the frames as the top windowDefault: _top | |  texts | - | object | UI element parameters | |    failedPaymentScreen | - | object | Failed payment screen | |      title | - | string | Failed payment message. Default value: Error| |    paymentForm | - | object | Payment form | |      buttonPayLabel | - | string | Payment button name. Default value: Pay | |      cardholderLabel | - | string | Cardholder name text. Default value: Cardholder | |      cardholderNote | - | string | Cardholder name prompt text. Default value: none | |      cardholderPlaceholder | - | string | Cardholder name placeholder. Default value: Full name | |      cardNumberLabel | - | string | Card number. Default value: Card number | |      cardNumberNote | - | string | Card number prompt text. Default value: none | |      cardNumberPlaceholder | - | string | Card number placeholder. Default value: 0000 0000 0000 0000 | |      cvvLabel | - | string | CVV/CVC number. Default value: CVC | |      cvvNote | - | string | CVV/CVC number prompt text. Default value: none | |      cvvPlaceholder | - | string | CVV/CVC number placeholder. Default value: CVC | |      expireDateLabel | - | string | Card expiration date. Default value: Expiration date | |      expireDateNote | - | string | Card expiration date prompt text. Default value: As stated on the card | |      expireDatePlaceholder | - | string | Card expiration date placeholder. Default value: MM/YY | |      recurrentLabel | - | string | Recurring payment checkbox. Default value: I agree to recurring payments | |      termsAgreement | - | string | Terms of agreement. The text within the mandatory {{#link}}{{/link}} tags is used as a link to the terms of agreement source. Default value: By pressing Pay, you accept the terms of our {{#link}}user agreement{{/link}} | |    validationErrors | - | object | Field validation error messages | |      INVALID_CARD_NUMBER | - | string | Invalid card number. Default value: Invalid card number | |      INVALID_CVV | - | string | Invalid CVV/CVC. Default value: CVV/CVC has 3 digits | |      INVALID_EXPIRY_DATE | - | string | Invalid card expiration date. Default value: Invalid date | |      IS_REQUIRED | - | string | Required field value is missing. Default value: Required field | |    paymentProcessScreen | - | object | Payment process page | |      description | - | string | Payment processing page text. Default value: Just a moment | |      title | - | string | Payment process screen heading. Default value: Payment processing... | |    redirectionScreen | - | object | Redirecting page (3D Secure) | |      followTheLink | - | string | Invitation message to proceed with redirection in case of automatic redirection failure. The text within the mandatory {{#link}}{{/link}} tags is used as a link. Default value: If you haven't been redirected automatically, use {{#link}}this link{{/link}}. | |      title | - | string | Payment processing page header. Default value: Payment processing... | |      waitForRedirectToBanksPage | - | string | Automatic redirection warning, includes 3 seconds countdown timer. The {{countdown}} value is mandatory and will be replaced with the timer. Use the {{#strong}}{{/strong}} tags to emphasize the timer in bold. Default value: You will be redirected to the issuer bank's page in {{#strong}}{{countdown}}seconds.{{/strong}}\ | |    successPaymentScreen | - | object | Successful payment page | |      title | - | string | Successful payment page header. Default value: Payment success | |    transactionData | - | object | Transaction data | |      amountLabel | - | string | Transaction amount label. Default value: Amount | |      creditCardLabel | - | string | Payment type data (card type and masked card number) label. Default value: Card | |      transactionIdLabel | - | string | Transaction ID label. Default value: Transaction ID | |    unknownError | - | string | Unknown error message. Default value: Something went wrong... | > \* Note that: > - We do not recommend using the _self option for security reasons. > - If you use the _blank option, the user will need to allow pop-ups in the browser or follow the redirection link from the payment widget. ### Method: paymentForm.render() The method displays the form on the page in the container defined by the options.container parameter. | Parameter | Mandatory | Type | Description | | ----------------- | --------- | ----------- | ----------------------------- | | options | - | Object | Additional settings object | | options.container | - | HTMLElement | Container into which the form will be inserted. Default value: | ### Event handlers #### paymentForm.onReady Handles the event of the form getting ready for work. #### paymentForm.onPaymentStart Handles the event occurring at the start of the payment process. #### paymentForm.onPaymentSuccess Handles the event occurring when the payment process finishes successfully. #### paymentForm.onPaymentFail Handles the event occurring when the payment process finishes unsuccessfully. #### paymentForm.onDestroy Handles the event of the widget getting closed. ### Customizing the widget appearance You can link your own styles at the end of the default ones and override them. > You cannot yet change the appearance of the values entered inside the iframe. This functionality will be added later. Also, you can modify texts of the widget UI elements. Here are what you can change: - labels - placeholders - error messages - prompt texts - button names - footer texts To do that, pass the Options object with UI element parameters within the [SmglPaymentForm](/docs/widget/payment-widget#smglpaymentform) widget constructor. #### Example of how to add a Spanish localization Click here to expand ### End user errors While interacting with our widget, end users may receive the errors stated below. >If you choose to translate the widget texts into other languages, for example, Spanish, note that for now end users will receive error descriptions still in English. | Error code | Error description | |-------------------------|--------------------------------------------------------------------------| | 3DS_error | To complete the transaction successfully, 3DS authentication is required | | activity_count_exceeded | The activity/amount limit for the card is exceeded | | bank_card_expired | The bank card is past its expiration date | | declined_by_issuer_bank | The operation was declined by the emitting bank | | insufficient_funds | The card does not have enough funds | | ---