# Smart Glocal API (Full) > Auto-generated full documentation content from llms.txt links ## 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/apms/momo) - [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) --- ## 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 [private 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. --- ## 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 and download transaction reports in CSV format](#registry) * find transactions using the [date filter or AI search](#searching) * see the [payout balances](#balances) ### 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**: QR code, 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 Smart Glocal 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 euros in the last quarter" in the search bar. ### Payout balances A payout balance is an amount that you can only spend on payouts to partners, clients, and contractors. To top up the payout account balance, please contact your Account Manager at Smart Glocal. You can use a single account for all payout types or create a dedicated account for each type. To view payout accounts, select the Balances section on the left panel. On the page that opens, you will see a carousel displaying all your payout accounts. When an account is selected, a statement for that account appears below. ## How to get access To get access to the Dashboard, contact your Account Manager at Smart Glocal. The access authorization document is signed by the company's director or Ultimate Beneficial Owner (UBO). Once the document is signed, the director or UBO receives administrator access to the Dashboard. From there, the administrator can provide access for their employees in the following steps: 1. Open the **Users** tab in the Dashboard. 2. Send an invitation to an employee's email, selecting their role. 3. The employee receives the invitation, sets up their account, and logs in with the assigned role. The Dashboard administrator will be able to: - add, re-invite, remove, or manage user accounts - block, delete, and restore a user's access to the Dashboard - reset a user's password if needed **Permission matrix** Below are the currently available roles, the list will be expanded as new functionality is added. You can assign multiple roles to a single user, as well as restrict their access to specific projects within the company. **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 | Submerchant identifier | #### Request example with authentication ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // request body }' ``` ### 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 private key and a public key. Using your public key Smart Glocal will verify signatures of your incoming requests. #### 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 private 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 private 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 ```openssl showLineNumbers # Generating a private key $ openssl genrsa -out private.pem 2048 # Generating a public key based on the private key $ openssl rsa -in private.pem -pubout > public.pem # Creating myfile.txt file contents $ echo test > myfile.txt # Generating a signature $ openssl dgst -sha256 -sign private.pem -out sha256.sign myfile.txt # Signature ready for transfer $ base64 sha256.sign # Checking the signature $ openssl dgst -sha256 -verify public.pem -signature sha256.sign myfile.txt Verified OK ``` ```php showLineNumbers $data = "test"; //Obtaining the pointer to the private and public keys $privateKey = openssl_pkey_get_private("file://private.pem"); $publicKey = openssl_pkey_get_public("file://public.pem"); //Generating a signature based on the data using the private key openssl_sign($data, $signature, $privateKey, OPENSSL_ALGO_SHA256); openssl_free_key($privateKey); //Encoding the signature into Base64 to transmit it $base64Signature = base64_encode($signature); //On receiving the signature, decoding it from Base64 $decodedSignature = base64_decode($base64Signature); //Validating the received signature using the public key (success = 1) $isValid = openssl_verify($data, $decodedSignature, $publicKey, OPENSSL_ALGO_SHA256); ``` ## 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 ```json showLineNumbers curl -X POST \ https://proxy.smart-glocal.com/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-IDEMPOTENCY-KEY: idempotency_key' \ -d '{ // request body }' ``` 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) --- ## 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 **USD** 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** - [Turkiye](/docs/payments/turkiye-cards): **American Express**, **Maestro Debit**, **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/apms/momo) - [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) ## Widget and payment page Smart Glocal offers two solutions to processing payments: the [payment widget](/docs/widget/payment-widget) and the [payment page](/docs/payments/payment-page). Study the [detailed comparison](/docs/payments/payment-solutions) to choose which solution best suits your business needs. ## 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 [card_id](/docs/reference/objects#card) parameter. 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. --- ## 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v2/session/create \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "usd" }, "participant_details": { "sender": { "full_name": "Helen Adams", "first_name": "Helen", "last_name": "Adams", "city": "Miesenbach", "street": "Templstrasse 8", "ipv4": "112.34.152.137", "postal_code": "93401", "email": "helen.adams@hotmail.com" } } }' ``` ## 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v2/session/create \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "usd" }, "participant_details": { "sender": { "full_name": "Helen Adams", "first_name": "Helen", "last_name": "Adams", "city": "Miesenbach", "street": "Templstrasse 8", "ipv4": "112.34.152.137", "postal_code": "93401", "email": "helen.adams@hotmail.com" } } }' ``` --- ## 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 | | participant_details | object | [Information on the participants](/docs/reference/objects#participant_details) | |   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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v2/session/create \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "usd" }, "items": [{ "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "white box", "amount_details": { "amount": 5000, "currency": "eur" }, "quantity": 1, "category_code": "general" }, { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d475", "name": "Black box", "amount_details": { "amount": 100, "currency": "eur" }, "quantity": 50, "category_code": "general" }], "participant_details": { "sender": { "country_iso3": "USA", "postal_code": "postal code", "email": "helen.adams@hotmail.com" } } }' ``` --- ## 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) ```plantuml @startuml Payment autonumber header Payment participant Partner participant Smart_Glocal as SG participant ACS Partner -> SG: sends ""session/create"" SG -> SG: creates a session SG --> Partner: sends 200 OK Partner -> SG: sends ""session/start/payment"" SG -> SG: starts the payment SG --> Partner: sends 200 OK SG -> Partner: sends ""ready_to_confirm"" webhook Partner --> SG: sends 200 OK Partner -> Partner: checks the details Partner -> SG: sends ""session/confirm"" SG --> Partner: sends 200 OK SG -> SG: checks if the card is \n involved in 3D Secure alt #faf1d7 The card is involved in 3d Secure SG -> Partner: sends ""action_required"" Partner --> SG: sends 200 OK Partner -> ACS: redirects the user for passing 3D Secure ACS -> SG: sends 3D Secure results end SG -> SG: withdraws the funds SG -> Partner: sends ""payment_finished"" Partner --> SG: sends 200 OK @enduml ``` To create a one-time payment using our payment widget, complete the following steps: 1. Complete [Steps 1 -- 5](/docs/widget/payment-widget#making-a-payment-using-the-widget). 2. 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. 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. > 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. 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) ```plantuml @startuml Payment with the widget autonumber header Payment with the widget participant Partner participant Smart_Glocal as SG participant SG_Widget as sgw participant ACS Partner -> SG: sends ""session/create"" SG -> SG: creates a session SG --> Partner: sends 200 OK Partner -> SG: requests public token SG -> SG: creates a token SG --> Partner: sends 200 OK and token details Partner -> sgw: calls ""render()"" rnote over sgw The user interacts with the widget endrnote sgw -> SG: initiates payment SG -> Partner: sends ""ready_to_confirm"" Partner --> SG: sends 200 OK Partner -> Partner: checks the details Partner -> SG: sends ""session/confirm"" SG --> Partner: sends 200 OK SG -> SG: checks if the card is \n involved in 3D Secure alt #faf1d7 The card is involved in 3d Secure SG -> sgw: sends data required for 3D Secure sgw -> ACS: redirects the user for passing 3D Secure ACS -> SG: sends 3D Secure results end SG -> SG: withdraws the funds SG -> Partner: sends ""payment_finished"" Partner --> SG: sends 200 OK SG -> sgw: sends payment details sgw -> sgw: shows payment status @enduml ``` --- ## 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) ```plantuml @startuml Delayed capture payment autonumber header Delayed capture payment participant Partner participant Smart_Glocal as SG participant ACS Partner -> SG: sends ""session/create"" SG -> SG: creates a session SG --> Partner: sends 200 OK Partner -> SG: sends ""session/start/payment"" SG -> SG: starts the payment SG --> Partner: sends 200 OK SG -> Partner: sends ""ready_to_confirm"" webhook Partner --> SG: sends 200 OK Partner -> Partner: checks the details Partner -> SG: sends ""session/confirm"" SG --> Partner: sends 200 OK SG -> SG: checks if the card is \n involved in 3D Secure alt #faf1d7 The card is involved in 3d Secure SG -> Partner: sends ""action_required"" Partner --> SG: sends 200 OK Partner -> ACS: redirects the user for passing 3D Secure ACS -> SG: sends 3D Secure results end SG -> SG: holds the funds SG -> Partner: sends ""ready_to_capture"" webhook Partner --> SG: sends 200 OK Partner -> SG: sends ""session/capture"" SG --> Partner: sends 200 OK SG -> SG: debits the funds SG -> Partner: sends ""payment_finished"" Partner --> SG: sends 200 OK @enduml ``` To create a delayed capture payment using our payment widget, complete the following steps: 1. Complete [Steps 1 -- 5](/docs/widget/payment-widget#making-a-payment-using-the-widget). 2. 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. 3. Confirm ([session/confirm](/docs/reference/methods/session-confirm)) or cancel the payment ([session/cancel](/docs/reference/methods/session-cancel)). > 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. 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) ```plantuml @startuml Delayed capture payment with the widget autonumber header Delayed capture payment with the widget participant Partner participant Smart_Glocal as SG participant SG_Widget as sgw participant ACS Partner -> SG: sends ""session/create"" SG -> SG: creates a session SG --> Partner: sends 200 OK Partner -> SG: requests public token SG -> SG: creates a token SG --> Partner: sends 200 OK and token details Partner -> sgw: calls ""render()"" rnote over sgw The user interacts with the widget endrnote sgw -> SG: initiates payment SG -> Partner: sends ""ready_to_confirm"" Partner --> SG: sends 200 OK Partner -> Partner: checks the details Partner -> SG: sends ""session/confirm"" SG --> Partner: sends 200 OK SG -> SG: checks if the card is \n involved in 3D Secure alt #faf1d7 The card is involved in 3d Secure SG -> sgw: sends data required for 3D Secure sgw -> ACS: redirects the user for passing 3D Secure ACS -> SG: sends 3D Secure results end SG -> SG: holds the funds SG -> Partner: sends ""ready_to_capture"" webhook Partner --> SG: sends 200 OK Partner -> SG: sends ""session/capture"" SG --> Partner: sends 200 OK SG -> SG: withdraws the funds SG -> Partner: sends ""payment_finished"" Partner --> SG: sends 200 OK SG -> sgw: sends payment details sgw -> sgw: shows payment status @enduml ``` --- ## Instant bank-to-bank transfers in India > Source: /docs/payments/india-accounts You can use India's 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 payment. 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 | [Payer's account description](/docs/reference/objects#bank_account) | |     system_type | 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 | Payment amount in minor units. To pay 100 INR, 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "bank_account", "bank_account": { "system_type": "upi", "upi": {} } }, "participant_details": { // highlight-start "sender": { "full_name": "Ram Devi", "email": "ramdevi@example.com", "document": "HSECT4378A", "msisdn": "8826320796", "state": "Goa", "city": "Goa", "street": "Maddo Vaddo", "building": "1207" } // highlight-end }, "amount_details": { "amount": 10000, // highlight-next-line "currency": "inr" }, "metadata": { "key": "value" }, "customer": { "reference": "qwiqwi" } }' ``` ### 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) --- ## 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 ```json {9} showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/refund \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_3230", "amount_details": { "amount": 1000, "currency": "usd" } }' ``` ### 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", // highlight-next-line "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890" } }, "amount_details": { "amount": 1000, "currency": "usd" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "amount_details": { "amount": 1000, "currency": "usd" } }], "transaction_info": { "rrn": "425307614918" } }] } }' ``` --- ## Payment solutions > Source: /docs/payments/payment-solutions Below is the information you need to make the right choice between Smart Glocal payment page and payment widget. Smart Glocal offers two solutions for processing payments: the [payment widget](/docs/widget/payment-widget) and the [payment page](/docs/payments/payment-page). | | Widget | Payment page | | ---------- | --------- | ------ | | **Integration** | Development required: you'll need to create sessions and handle the widget initialization and rendering on your side | Fast launch: all you need is to create a payment link, then the customer is redirected to the payment page and returns to your site after a payment attempt. The payment link can even be shared via a messenger | | **Payment interface** | The widget UI is customizable: you can edit all texts, set up your fonts and colors. Note: the appearance of values typed inside the card iframe cannot be changed yet | The UI is provided by the page, you can only select the light or dark scheme | | **Embedding the payment form** | Yes: the widget is embedded directly into your page (rendered in a container/iframe) | No: the payment page is a hosted, redirect-based solution and cannot be embedded | | **Payment methods** | Supports only a single payment method (you need to choose and set up the payment method on your side) | Multiple payment methods available. The customer can select the payment method when placing the order | | **Payment attempts and conversion** | If a payment fails, the customer needs to start the payment over | If a payment fails, the customer can retry on the same page, no actions needed on your side | | **Currencies** | Multiple currencies supported. The widget can show the converted target amount at a guaranteed rate, and shows how long the rate is held | Single currency only, without conversion | #### What to choose for your payments Choose the [payment widget](/docs/widget/payment-widget) in case: - You need currency conversion support. - You want to embed the payment form on your website with iframe. Choose the [payment page](/docs/payments/payment-page) in case: - You need simple integration of the payment solution. - You need support of several payment methods out-of-the-box. - You want to be able to send the payment link in a messenger. --- ## Payment page for accepting payments > Source: /docs/payments/payment-page Smart Glocal payment page is a ready-to-use solution for accepting payments. It works as both an on-site checkout page and a [shareable payment link](#manual_payment_link) via a [simple API](#API). ## Payment page for your customer Your customer places an order on your website, then gets redirected to the payment page, and we handle everything from there. You have the options to let the customer select the preferred payment method or specify the payment method directly in the [request](#payment_link). If the first payment attempt fails, the page automatically prompts a retry at the same link --- no page reload needed, so you do not lose the customer. A new payment session is created automatically, no action on your part is needed. You will receive a [daily report on successful payments](/docs/finance/payment-daily-report). You can select the color theme that best fits your service's interface so that the payment page feels like part of your website. Light and dark themes supported ## Generating a payment link The same API can be used not only for an on-site checkout, but also to generate standalone payment links --- for example, to share with customers directly via email, messengers, or social media. This is particularly convenient for: - **Email campaigns** --- generate a link per recipient and embed it in your mailer - **Social media/messengers** --- post the link in a story, bio, or send it directly in a chat - **Chatbots** --- connect the API call to your Telegram or WhatsApp bot so it issues a fresh payment link on demand - **Manual invoicing** --- generate a link in Postman, copy it, send it in any way you like :::info[Important!] Please contact your Smart Glocal manager to set up this feature for your business. ::: To use this feature, call the [POST/payment_link](#payment_link) method using one of the following approaches: - **HTTP client** (e.g., Postman) --- send the request manually, copy payment_page_url from the response, and paste it wherever you need: an email, a social media post, a messenger chat. - **No-code automation platform** (e.g., Make or Zapier) --- set up a scenario that calls the API automatically and passes the link to your mailer, Telegram bot, or any other channel. :::warning[Description is required] You should always provide a clear, detailed description of the product or service being paid for. This is required for payment processing and helps avoid disputes, chargebacks, and complications with refunds. ::: Each link does not expire if a payment attempt fails. In this case, a new payment session will be created automatically once the customer retries the payment, there is no need to generate a new payment link. ## How to process payments via API #### Step 1. Create a payment link ([POST/payment_link](#payment_link)) Send a [POST/payment_link](#payment_link) request to create a payment link. In the request, specify the amount, currency, item list, and (optionally) payment methods. In response, you will receive a payment link, which you can then provide to the customer. :::note[] A payment link remains valid during the time specified in the active_to field or until you get an [order_finished](/docs/reference/webhooks/order-finished) webhook, whichever happens first. ::: [Learn more on the request format](/docs/reference/format) Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/payment_link \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-start "amount_details": { "amount": 10000, "currency": "eur" // highlight-end }, "customer": { "reference": "customer" }, // highlight-start "payment_methods": [{ "type": "faster_payment_system" }], // highlight-end "payment_options": { "success_return_url": "https://test.dev", "failure_return_url": "https://test.dev" }, // highlight-next-line "items": [{ "amount_details": { "amount": 10000, "currency": "eur" }, "id": "5179a750-c0b0-4211-b3b1-12a72242b1a4", "name": "Premium Pro subscription", "quantity": 1 }], "metadata": { "internal_id": "x-123-456", "extra": "z-aaa-bbb" }, "description": "Payment #x-123-456 by shop1.com" }' ``` #### Step 2. Forward the customer By any convenient means, direct the customer to the payment page using the payment link. #### Step 3. Wait for a webhook confirming the payment is ready Wait for a [ready_to_confirm](/docs/reference/webhooks/ready-to-confirm) webhook. This means that the payment can be performed and Smart Glocal is waiting for you to confirm. It will contain the user identifier (customer.reference) and your identifiers (metadata), if you passed these parameters in the [POST/payment_link](#payment_link) request. The webhook also provides session.id, which you can then use to start polling the payment status (using the [session/status](/docs/reference/methods/session-status) method) if needed. Verify that the details in the webhook are correct and send HTTP 200 OK in response. Webhook example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", // highlight-start "session": { "id": "ps_3230", // highlight-end "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", "acquiring_payments": [{ "id": "pm_1313", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", // highlight-start "customer": { "reference": "customer" }, // highlight-end "payment_details": { "type": "card", "card": { "last4": "7890", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "eur" }, // highlight-start "metadata": { "internal_id": "x-123-456", "extra": "z-aaa-bbb" }, // highlight-end "description": "Payment #x-123-456 by shop1.com" }] } }' ``` #### Step 4. Confirm or cancel the payment 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. #### Step 5. Wait for a webhook with the results You may receive multiple [payment_finished](#payment-f) webhooks with the status of each payment attempt and a single [order_finished](#order-f) webhook with the status of the order (once the order is completed and the link is no longer valid). ##### [payment_finished](/docs/reference/webhooks/payment-finished) The result of the payment attempt can be found in the status field of the acquiring_payments/payment_list array: - succeeded means the payment has been successful. This is the final status. - failed means the current payment attempt has not been completed because of an [error](/docs/reference/errors). Webhook example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_1313", // highlight-next-line "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "customer" }, "payment_details": { "type": "card", "card": { "last4": "7890", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "eur" }, "metadata": { "internal_id": "x-123-456", "extra": "z-aaa-bbb" }, "description": "Payment #x-123-456 by shop1.com" }] } }' ``` ##### [order_finished](/docs/reference/webhooks/order-finished) You receive this webhook when an order is completed and the payment link is no longer valid. The webhook contains the order identifier and status. If the status is success, the payment was successful. If the status is failed, the payment failed for the reason returned in the webhook. Webhook example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "order_finished", "order": { "order_id": "bYGR1PLkQ45Z7Vm9zJQx9G", "status": "success", "reason": null } }' ``` ## Recurring payments With the payment page, you can accept MIT recurring payments: the customer gives their consent for repeated payments and makes the initial payment. Then you can initiate recurring payments without the customer's involvement on your own schedule. When creating a payment link, pass the link_options.is_recurrent: true value in the [POST/payment_link](#payment_link) request. When the user opens the payment link, they will see a checkbox to consent to subsequent charges. Payment page with the recurring payments option If the user checks this box and the payment is successful, you will receive a token in the [recurrent](/docs/reference/objects#recurrent_info) object of the [payment_finished](/docs/reference/webhooks/payment-finished) webhook. [How to check a token status](/docs/payments/payment-recurring#managing-your-tokens) Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/payment_link \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "eur" }, "description": "Payment for order #12345", "link_options": { // highlight-next-line "is_recurrent": true }, "metadata": { "internal_id": "x-123-456", "extra": "z-aaa-bbb" }, "payment_methods": [{ "type": "card" }], "payment_options": { "success_return_url": "https://shop.example.com/success", "failure_return_url": "https://shop.example.com/fail" } }' ``` ### How to make recurring payments 1. Create a payment session sending a [session/create](/docs/reference/methods/session-create) request. 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. Pass initiator: merchant in the [recurrent](/docs/reference/objects#recurrent_token) object of payment_details or do not specify the initiator at all. Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_3230", "payment_details": { "type": "recurrent", "recurrent": { "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39", // highlight-next-line "initiator": "merchant" } }, "amount_details": { "amount": 10000, "currency": "eur" }, "customer": { "reference": "customer" } }' ``` 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). ## POST/payment_link Use this request to get a payment link. You can pass the payment method, order description, item list, and amount in the request. >If a list of items is passed, the payer will see them on the payment page. #### Request parameters | Name | Mandatory | Type | Description | |----------------------------------|-----------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | amount_details | + | object | [Payment amount details](/docs/reference/objects#amount_details) | |   amount | + | int | Payment amount in minor currency units. To send 100 EUR, write 10000 | |   currency | + | string | ISO 4217 currency code. Case insensitive | | customer | - | object | Data about the customer in your system | |   reference | + | string | Customer identifier in your system | | payment_methods | - | array | Payment method details. Do not pass the array if you want the user to have access to all payment methods enabled for you.To offer only certain payment methods, pass them. Example: "payment_methods": [{"type": "faster_payment_system"}, {"type": "card"}] | |   type | + | string | Payment method name. Options:- faster_payment_system --- payment via the Faster Payment System - card --- payment by card | | payment_options | - | object | [Additional payment parameters](/docs/reference/objects#payment_options) | |   return_url | - | string | URL by which the user can return to the site at any time | |   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 | | link_options | - | object | Additional payment page parameters | |   lang | - | string | Payment page language. Default value: en | |   theme | - | string | Payment page theme. Options: dark, light. Default value: light | |   is_recurrent | - | boolean | Specifies whether the payment page offers the option to agree to recurring payments. If is_recurrent = true, a dedicated checkbox for recurring charges will be shown on the page | | metadata | - (mandatory for submerchants) | * | [Any additional information](/docs/reference/objects#metadata). If the transaction is processed by a submerchant, specify the payment site: "metadata": {"submerchant": "https://website.com"} | | description | + | string | Text to be displayed to the user on the payment page. Example: Order number 345 | | items | - | array | List of purchased items | |   id | + | string | Product item UUID in your system | |   name | + | string | Item name | |   quantity | + | int | Quantity of items | |   amount_details | + | object | Amount details | |     amount | + | int | Item price. The total amount for all the items must match the total of the transaction | |     currency | + | string | Item price currency. The currency must match the currency of the transaction | Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/payment_link \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "eur" }, "customer": { "reference": "customer" }, "payment_methods": [{ "type": "faster_payment_system" }], "payment_options": { "success_return_url": "https://test.dev", "failure_return_url": "https://test.dev" }, "items": [{ "amount_details": { "amount": 10000, "currency": "eur" }, "id": "5179a750-c0b0-4211-b3b1-12a72242b1a4", "name": "Premium Pro subscription", "quantity": 1 }], "metadata": { "internal_id": "x-123-456", "extra": "z-aaa-bbb" }, "description": "Payment #x-123-456 by shop1.com" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |--------------------------------|-----------|----------|----------------------------------------------------| | order | + | object | Order details | |   order_id | - | string | Payment link ID | |   payment_page_url | - | string | Payment link | |   active_to | - | dateTime | Payment link expiration date in ISO 8601 format | | error | - | object | [Error description](/docs/reference/objects#error) | Response example ```json showLineNumbers { "order": { "order_id": "B0k84LoQwKPq", "payment_page_url": "https://checkout-demo.smart-glocal.com/pay/ceMjRsrRNRcU4p3G4qLkqx", "active_to": "2026-04-24T14:39:43.000000Z" } } ``` ## Working with request signatures ### 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 private key and a public key. Using your public key Smart Glocal will verify signatures of your incoming requests. ##### 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 private 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 private 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 ```openssl showLineNumbers # Generating a private key $ openssl genrsa -out private.pem 2048 # Generating a public key based on the private key $ openssl rsa -in private.pem -pubout > public.pem # Creating myfile.txt file contents $ echo test > myfile.txt # Generating a signature $ openssl dgst -sha256 -sign private.pem -out sha256.sign myfile.txt # Signature ready for transfer $ base64 sha256.sign # Checking the signature $ openssl dgst -sha256 -verify public.pem -signature sha256.sign myfile.txt Verified OK ``` ```php showLineNumbers $data = "test"; //Obtaining the pointer to the private and public keys $privateKey = openssl_pkey_get_private("file://private.pem"); $publicKey = openssl_pkey_get_public("file://public.pem"); //Generating a signature based on the data using the private key openssl_sign($data, $signature, $privateKey, OPENSSL_ALGO_SHA256); openssl_free_key($privateKey); //Encoding the signature into Base64 to transmit it $base64Signature = base64_encode($signature); //On receiving the signature, decoding it from Base64 $decodedSignature = base64_decode($base64Signature); //Validating the received signature using the public key (success = 1) $isValid = openssl_verify($data, $decodedSignature, $publicKey, OPENSSL_ALGO_SHA256); ``` ### Integration instructions Please study the following before starting the integration process: - [Quick start guide](/docs/before) - [API interaction](/docs/reference/format) - [Testing](/docs/reference/testing) ## Sequence diagram ![sequenceDiagram](/img/docs/yora/several_attempts.png) ```plantuml @startuml One-time payment autonumber header One-time payment participant User participant Partner participant Payment_Page as PP participant Backend as BE ==create payment link== User -> Partner: Wants to pay for an item Partner -> BE: sends ""payment_link"" BE --> Partner: sends 200 OK Partner -> User: shows the link to the user ==payment attempt 1 (failed)== User -> PP: follows the link to the payment page,\nclicks Pay and selects payment method rnote over Partner, BE Payment starts (attempt 1) endrnote BE -> BE: creates a session BE -> Partner: sends ""ready_to_confirm"" Partner --> BE: sends 200 OK Partner -> Partner: checks details Partner -> BE: sends ""session/confirm"" BE --> Partner: sends 200 OK rnote over Partner, BE Payment by card/by QR code endrnote BE -> Partner: sends ""payment_finished"" status=failed Partner --> BE: sends 200 OK PP -> PP: transaction status page (failed) User -> PP: sees failed status ==payment attempt 2 (successful)== User -> PP: retries payment,\nclicks Pay and selects payment method again rnote over Partner, BE Payment starts (attempt 2) endrnote BE -> BE: creates a new session BE -> Partner: sends ""ready_to_confirm"" Partner --> BE: sends 200 OK Partner -> Partner: checks details Partner -> BE: sends ""session/confirm"" BE --> Partner: sends 200 OK rnote over Partner, BE Payment by card/by QR code endrnote BE -> Partner: sends ""payment_finished"" status=succeeded Partner --> BE: sends 200 OK BE -> Partner: sends ""order_finished"" status=success Partner --> BE: sends 200 OK PP -> PP: transaction status page (successful) User -> PP: sees successful status @enduml ``` ![sequenceDiagram](/img/docs/yora/payment_page_recurring.png) ```plantuml @startuml Recurring payment autonumber header Recurring payment participant User participant Partner participant Payment_Page as PP participant Backend as BE ==payment day== Partner -> BE: sends ""payment_link""\n""link_options.is_recurrent"" = true BE --> Partner: sends payment link Partner -> User: shows the link to the user User -> PP: follows the link to the payment page,\nchecks recurring checkbox rnote over User, BE Successful payment endrnote BE -> Partner: sends ""payment_finished""\nwith token in the ""recurrent"" object Partner --> BE: sends 200 OK BE -> Partner: sends ""order_finished"" status=success Partner --> BE: sends 200 OK ==subscription payment day== Partner -> BE: sends ""session/create"" BE --> Partner: sends 200 OK Partner -> BE: sends ""session/start/payment""\n""type"" = ""recurrent"", token,\n""initiator"" = ""merchant"" BE --> Partner: sends 200 OK BE -> Partner: sends ""ready_to_confirm"" Partner --> BE: sends 200 OK Partner -> BE: sends ""session/confirm"" BE --> Partner: sends 200 OK BE -> BE: withdraws the funds BE -> Partner: sends ""payment_finished"" Partner --> BE: sends 200 OK @enduml ``` --- ## Performing payments with the widget > Source: /docs/widget/payment-widget You can use our payment form widget to perform payments. ```html showLineNumbers Payment form widget
``` ## Getting started To start using our widget, do the following: ### Link the scripts and styles In test environment ```html showLineNumbers ``` For real payments ```html showLineNumbers ``` ### Add the widget container ```html
``` 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 ```json {9-10} showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "acquiring_widget": { "session_id": "ps_34851", "show_recurrent_checkbox": true, "locale":"en" } }' ``` > 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 ```js const paymentForm = new SmglPaymentForm(publicToken); ``` 4. To display the payment form, call the render() method: Example ```js paymentForm.render(); ``` 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. ```js const paymentForm = new SmglPaymentForm(publicToken[, options]) ``` | 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. ```js paymentForm.render([options]) ``` | 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. ```js showLineNumbers paymentForm.onReady = function () { /* handler */ } ``` #### paymentForm.onPaymentStart Handles the event occurring at the start of the payment process. ```js showLineNumbers paymentForm.onPaymentStart = function () { /* handler */ } ``` #### paymentForm.onPaymentSuccess Handles the event occurring when the payment process finishes successfully. ```js showLineNumbers paymentForm.onPaymentSuccess = function () { /* handler */ } ``` #### paymentForm.onPaymentFail Handles the event occurring when the payment process finishes unsuccessfully. ```js showLineNumbers paymentForm.onPaymentFail = function (error) { /* handler */ } ``` #### paymentForm.onDestroy Handles the event of the widget getting closed. ```js showLineNumbers paymentForm.onDestroy = () => { /* handler */ } ``` ### Customizing the widget appearance You can link your own styles at the end of the default ones and override them. ```html showLineNumbers ``` ```css showLineNumbers /* custom-styles.css */ .smgl-Field__label { color: green; } ``` > 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 ```javascript showLineNumbers const paymentForm = new SmglPaymentForm('', { isCvcMasked: true, texts: { failedPaymentScreen: { title: 'Error', }, paymentForm: { buttonPayLabel: 'Pagar', cardholderLabel: 'Titular de la tarjeta', cardholderNote: '', cardholderPlaceholder: 'Nombre completo', cardNumberLabel: 'Numero de tarjeta', cardNumberNote: '', cardNumberPlaceholder: '0000 0000 0000 0000', cvvLabel: 'CVC', cvvNote: '', cvvPlaceholder: 'CVC', expireDateLabel: 'Fecha de vencimiento', expireDateNote: '', expireDatePlaceholder: 'MM/AA', recurrentLabel: 'Autorizo pagos recurrentes', termsAgreement: 'Al presionar Pagar, Ud. acepta los terminos de nuestro {{#link}}acuerdo de usuario{{/link}}', }, validationErrors: { INVALID_CARD_NUMBER: 'Numero de tarjeta invalido', INVALID_CVV: 'CVV/CVC tiene 3 digitos', INVALID_EXPIRY_DATE: 'Fecha invalida', IS_REQUIRED: 'Campo requerido', }, paymentProcessScreen: { description: 'Espere un momento', title: 'Procesando el pago...', }, redirectionScreen: { followTheLink: 'Si Ud. no es redirigido automaticamente, use {{#link}}este enlace{{/link}}.', title: 'Procesando el pago...', waitForRedirectToBanksPage: 'Sera redirigido a la pagina web del banco emisor en {{#strong}}{{countdown}} segundos{{/strong}}.', }, successPaymentScreen: { title: 'Exito', }, transactionData: { amountLabel: 'Cantidad', creditCardLabel: 'Tarjeta', transactionIdLabel: 'ID de transaccion', }, unknownError: 'Algo salio mal...', }, }); ``` ### 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 issuer bank | | insufficient_funds` | The card does not have enough funds | --- ## Currency conversion with the widget > 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/create \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 1000, "currency": "eur" }, "participant_details": { "recipient": { "full_name": "John Richards" } }, "customer": { "reference": "smgl_widget_test" } }' ``` Response example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "status": "ok", "session": { "id": "ps_3240", "status": "created", "created_at": "2026-02-25T11:44:26.920749Z", "updated_at": "2026-02-25T11:44:26.920749Z", // highlight-start "exchange_amounts": [{ "source": { "amount": 1000, "currency": "eur" }, "destination": { "amount": 1359, "currency": "usd" }, "rate": 1.358822, "rate_source": "oer", "reserved_to": 1772019896 // highlight-end }] } }' ``` 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "acquiring_widget": { "session_id": "ps_3240" } }' ``` 3. Use the returned public token to initialize the widget. Example ```js const paymentForm = new SmglPaymentForm(publicToken); ``` 4. To display the payment form, call the render() method: Example ```js paymentForm.render(); ``` 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. If the user fails to pay within the specified time, an error will be displayed and the transaction will need to be restarted. 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3240", "status": "accepted", "created_at": "2026-02-23T16:03:03.860365Z", "updated_at": "2026-02-23T16:03:31.059975Z", "acquiring_payments": [{ "id": "pm_5810", "status": "succeeded", "created_at": "2026-02-23T16:03:30.908738Z", "finished_at": "2026-02-23T16:03:31.033735Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890", "country_iso3": "GBR" } }, "amount_details": { "amount": 1000, "currency": "eur" }, "amounts": { "fee": { "merchant_fee": { "amount": 1, "currency": "eur" }, "submerchant_custom_fee": { "amount": 1, "currency": "eur" } } } }], "actions": { "confirm": "2026-02-23T16:03:30.950008Z", "capture": "2026-02-23T16:03:30.998963Z" }, "exchange_amounts": [{ "source": { "amount": 1000, "currency": "eur" }, "destination": { "amount": 1359, "currency": "usd" }, "rate": 1.358822, "rate_source": "oer", "reserved_to": 1772019896 }] } }' ``` --- ## 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, document | 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 | Minimum amount: 1 INRAdditionally 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| | [Qatar](/docs/payments/qatar-cards) | QAR | full_name, email, document |Minimum amount: 1 QAR| | [Saudi Arabia](/docs/payments/saudi-arabia-cards) | SAR | full_name, email, document |Minimum amount: 1 SAR| | [Thailand](/docs/payments/thailand-cards) | THB | full_name, email, document |Minimum amount: 1 THB| | [Turkiye](/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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "30", "security_code": "123" } } }, "participant_details": { // highlight-start "sender": { "full_name": "Jane Doe", "email": "janedoe@mymail.com", "document": "12345678901" } // highlight-end }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" }, "amount_details": { "amount": 10000, // highlight-next-line "currency": "brl" } }' ``` --- ## 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "30", "security_code": "123" } } }, "participant_details": { // highlight-start "sender": { "full_name": "Jane Doe", "email": "janedoe@mymail.com" } // highlight-end }, "amount_details": { "amount": 10000, // highlight-next-line "currency": "clp" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" } }' ``` --- ## 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "30", "security_code": "123" } } }, "participant_details": { // highlight-start "sender": { "full_name": "Jane Doe", "email": "janedoe@mymail.com", "document": "12345678901" } // highlight-end }, "amount_details": { "amount": 20000, // highlight-next-line "currency": "cop" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" } }' ``` --- ## 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 Credit, Visa Debit, Mastercard Credit, 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "30", "security_code": "123" } } }, "participant_details": { // highlight-start "sender": { "full_name": "Jane Doe", "email": "janedoe@mymail.com", "document": "EHFGA5967A", "msisdn": "8826320796", "state": "Goa", "city": "Goa", "street": "Maddo Vaddo", "building": "1207", "postal_code": "403001" } // highlight-end }, "amount_details": { "amount": 10000, // highlight-next-line "currency": "inr" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" } }' ``` --- ## 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 Credit, Visa Debit, Mastercard Credit, 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "30", "security_code": "123" } } }, "participant_details": { // highlight-start "sender": { "full_name": "Jane Doe", "email": "janedoe@mymail.com", "document": "1234567890123456" } // highlight-end }, "amount_details": { "amount": 1100000, // highlight-next-line "currency": "idr" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" } }' ``` --- ## 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "30", "security_code": "123" } } }, "participant_details": { // highlight-start "sender": { "full_name": "Jane Doe", "email": "janedoe@mymail.com" } // highlight-end }, "amount_details": { "amount": 10000, // highlight-next-line "currency": "mxn" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" } }' ``` --- ## 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 Credit, Visa Debit, Mastercard Credit, 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "30", "security_code": "123" } } }, "participant_details": { // highlight-start "sender": { "full_name": "Jane Doe", "email": "janedoe@mymail.com" } // highlight-end }, "amount_details": { "amount": 10000, // highlight-next-line "currency": "ngn" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" } }' ``` --- ## 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "30", "security_code": "123" } } }, "participant_details": { // highlight-start "sender": { "full_name": "Jane Doe", "email": "janedoe@mymail.com", "document": "123456789012" } // highlight-end }, "amount_details": { "amount": 10000, // highlight-next-line "currency": "php" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" } }' ``` --- ## Local card payments in Qatar > Source: /docs/payments/qatar-cards You can make local card payments in Qatar. Currency: **QAR** Minimum payment amount: **1 QAR** Maximum payment amount: **unlimited** Available payment systems: **Visa Credit, Visa Debit, Mastercard Credit, Mastercard Debit, Naps 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 | National ID card (11 digits) | ### Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "10", "expiration_year": "40", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "qar" }, "customer": { "reference": "lucky" }, "payment_options": { "recurrent": false, "return_url": "https://website.com" }, "participant_details": { "sender": { "full_name": "Jane Doe", "document": "12345678901", "email": "janedoe@mymail.com" } } }' ``` --- ## Local card payments in Saudi Arabia > Source: /docs/payments/saudi-arabia-cards You can make local card payments in Saudi Arabia. Currency: **SAR** Minimum payment amount: **1 SAR** Maximum payment amount: **unlimited** Available payment systems: **Visa Credit, Visa Debit, Mastercard Credit, Mastercard Debit, Mada** 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 | National ID card (10 digits) | ### Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "10", "expiration_year": "40", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "sar" }, "customer": { "reference": "lucky" }, "payment_options": { "recurrent": false, "return_url": "https://website.com" }, "participant_details": { "sender": { "full_name": "Jane Doe", "document": "1234567890", "email": "janedoe@mymail.com" } } }' ``` --- ## 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 Credit, Visa Debit, Mastercard Credit, 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "30", "security_code": "123" } } }, "participant_details": { // highlight-start "sender": { "full_name": "Jane Doe", "email": "janedoe@mymail.com", "document": "1234567890123" } // highlight-end }, "amount_details": { "amount": 10000, // highlight-next-line "currency": "thb" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" } }' ``` --- ## Local card payments in Turkiye > Source: /docs/payments/turkiye-cards You can make local card payments in Turkiye. :::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 Debit, 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. (11 digits) | ### Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "30", "security_code": "123" } } }, "participant_details": { // highlight-start "sender": { "full_name": "Jane Doe", "email": "janedoe@mymail.com", "document": "12345678901" } // highlight-end }, "amount_details": { "amount": 10000, // highlight-next-line "currency": "try" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" } }' ``` --- ## Local card payments in Vietnam > Source: /docs/payments/vietnam-cards You can make local card payments in Vietnam. Currency: **VND** Minimum payment amount: **5,000 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 | VNID (9 to 13 digits) | ### Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "30", "security_code": "123" } } }, "participant_details": { // highlight-start "sender": { "full_name": "Jane Doe", "email": "janedoe@mymail.com", "document": "0123456789012" } // highlight-end }, "amount_details": { "amount": 500000, // highlight-next-line "currency": "vnd" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" } }' ``` --- ## MoMo payments in Vietnam > Source: /docs/payments/apms/momo You can make MoMo payments in Vietnam in Vietnamese dong (VND). >No recurring payments are available. ### 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 | VNID (9 to 13 digits) | |     msisdn | string | Phone number (up to 15 characters, without + ) | ## 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_momo in internet_banking.type - country_iso2 in internet_banking.country_ewallet - the payer's full_name, email, msisdn, and document 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_5666", "payment_details": { "type": "internet_banking", "internet_banking": { // highlight-start "type": "country_ewallet_momo", "country_ewallet": { "country_iso2": "VN" // highlight-end } } }, "amount_details": { "amount": 100000, "currency": "vnd" }, "customer": { "reference": "qwiqwi" }, "participant_details": { // highlight-start "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "12333315123", "msisdn": "12345678901" } // highlight-end }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }' ``` Response example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "status": "ok", "session": { "id": "ps_5666", "status": "in_progress", "created_at": "2025-12-04T19:28:58.077701Z", "updated_at": "2025-12-04T19:29:23.216667Z", "acquiring_payments": [{ "id": "pm_12354", "status": "in_progress", "created_at": "2025-12-04T19:29:23.217101Z", "customer": { "reference": "qwiqwi" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_momo", "country_ewallet": { "country_iso2": "VN" } } }, "amount_details": { "amount": 100000, "currency": "vnd" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "12333315123", "msisdn": "12345678901" } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }] } }' ``` 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "status": "ok", "session": { "id": "ps_5666", "status": "in_progress", "created_at": "2025-12-04T19:28:58.077701Z", "updated_at": "2025-12-04T19:29:23.216667Z", "acquiring_payments": [{ "id": "pm_12354", "status": "pending", "created_at": "2025-12-04T19:29:23.217101Z", "customer": { "reference": "qwiqwi" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_momo", "country_ewallet": { "country_iso2": "VN" } } }, "amount_details": { "amount": 100000, "currency": "vnd" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "12333315123", "msisdn": "12345678901" } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.275964Z" } } }' ``` 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/confirm \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_5666" }' ``` 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "status": "ok", "session": { "id": "ps_5666", "status": "in_progress", "created_at": "2025-12-04T07:48:28.296138Z", "updated_at": "2025-12-04T07:48:28.958891Z", "acquiring_payments": [{ "id": "pm_12354", "status": "pending", "created_at": "2025-12-04T07:48:28.296138Z", "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "12333315123", "msisdn": "12345678901" } }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_momo", "country_ewallet": { "country_iso2": "VN" } } }, "amount_details": { "amount": 100000, "currency": "vnd" }, "customer_interaction": { "type": "redirect", "redirect": { // highlight-next-line "url": "https://redirect-url-example.com/12345", "base_url": "https://redirect-url-example.com/12345", "method": "GET", "params": {} } }, "metadata": { "key": "value" }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.327146Z" } } }' ``` 5.1 The user redirected by the link from the webhook lands on a payment page. 5.2 The user selects a payment method and the QR code appears. 5.3 After the user completes the payment, a message on successful payment appears. 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "status": "ok", "session": { "id": "ps_5666", "status": "accepted", "created_at": "2025-12-04T07:48:28.275964Z", "updated_at": "2025-12-04T07:49:43.022068Z", "acquiring_payments": [{ "id": "pm_12354", "status": "succeeded", "created_at": "2025-12-04T07:48:28.296138Z", "finished_at": "2025-12-04T07:49:43.002789Z", "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "12333315123", "msisdn": "12345678901" } }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_momo", "country_ewallet": { "country_iso2": "VN" } } }, "amount_details": { "amount": 100000, "currency": "vnd" }, "metadata": { "key": "value" }, "payment_options": { "return_url": "https://smart-glocal.com", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.327146Z", "capture": "2025-12-04T07:49:42.965552Z" } } }' ``` ### Sequence diagram ![](/img/docs/payments/momo/momo.png) ```plantuml @startuml momo payment autonumber header MoMo payments actor Customer participant Partner participant Smart_Glocal as SG Customer -> Partner: wants to make a payment Partner -> SG: sends ""session/create"" SG -> SG: creates a session SG --> Partner: sends 200 OK Partner -> SG: sends ""session/start/payment"" SG -> SG: starts the payment SG --> Partner: sends 200 OK SG -> Partner: sends ""ready_to_confirm"" webhook Partner --> SG: sends 200 OK Partner -> Partner: checks the details Partner -> SG: sends ""session/confirm"" SG --> Partner: sends 200 OK SG -> Partner: sends ""action_required"" Partner --> SG: sends 200 OK Partner -> Customer: displays the payment page Customer -> Customer: makes the payment SG -> SG: withdraws the funds SG -> Partner: sends ""payment_finished"" Partner --> SG: sends 200 OK Partner -> Customer: informs of the payment results @enduml ``` --- ## OPay payments in Nigeria > Source: /docs/payments/apms/opay You can make local OPay payments in Nigeria in Nigerian naira (NGN). >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_opay in internet_banking.type - country_iso2 = NG in internet_banking.country_ewallet - the payer's full_name, email, and 11-digit NIN in document 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_12345", "payment_details": { "type": "internet_banking", "internet_banking": { // highlight-start "type": "country_ewallet_opay", "country_ewallet": { "country_iso2": "NG" // highlight-end } } }, "amount_details": { "amount": 10000, "currency": "ngn" }, "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { // highlight-start "full_name": "Name Surname", "email": "email@example.com", "document": "12345678901" // highlight-end } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }' ``` Response example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2025-12-04T19:28:58.077701Z", "updated_at": "2025-12-04T19:29:23.216667Z", "acquiring_payments": [{ "id": "pm_12354", "status": "in_progress", "created_at": "2025-12-04T19:29:23.217101Z", "customer": { "reference": "qwiqwi" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_opay", "country_ewallet": { "country_iso2": "NG" } } }, "amount_details": { "amount": 10000, "currency": "ngn" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "12345678901" } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }] } }' ``` 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2025-12-04T19:28:58.077701Z", "updated_at": "2025-12-04T19:29:23.216667Z", "acquiring_payments": [{ "id": "pm_12354", "status": "pending", "created_at": "2025-12-04T19:29:23.217101Z", "customer": { "reference": "qwiqwi" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_opay", "country_ewallet": { "country_iso2": "NG" } } }, "amount_details": { "amount": 10000, "currency": "ngn" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "12345678901" } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.275964Z" } } }' ``` 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/confirm \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_12345" }' ``` 5. Wait for an [action_required](/docs/reference/webhooks/action-required) webhook. The customer_interaction.redirect.url parameter contains a link to the local payment method page. Webhook example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2025-12-04T07:48:28.296138Z", "updated_at": "2025-12-04T07:48:28.958891Z", "acquiring_payments": [{ "id": "pm_12354", "status": "pending", "created_at": "2025-12-04T07:48:28.296138Z", "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "12345678901" } }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_opay", "country_ewallet": { "country_iso2": "NG" } } }, "amount_details": { "amount": 10000, "currency": "ngn" }, "customer_interaction": { "type": "redirect", "redirect": { // highlight-next-line "url": "https://redirect-url-example.com/12345", "base_url": "https://redirect-url-example.com/12345", "method": "GET", "params": {} } }, "metadata": { "key": "value" }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.327146Z" } } }' ``` 5.1 The user redirected by the link from the webhook (customer_interaction.redirect.url) lands on a page with payment data: 5.2 The user gets authenticated by phone number and selects a payment method. 5.3 The user enters a verification code. 5.4 After the user completes the payment, the page shows a successful payment message. 6. After the user 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "status": "ok", "session": { "id": "ps_12345", "status": "accepted", "created_at": "2025-12-04T07:48:28.275964Z", "updated_at": "2025-12-04T07:49:43.022068Z", "acquiring_payments": [{ "id": "pm_12354", "status": "succeeded", "created_at": "2025-12-04T07:48:28.296138Z", "finished_at": "2025-12-04T07:49:43.002789Z", "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "12345678901" } }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_opay", "country_ewallet": { "country_iso2": "NG" } } }, "amount_details": { "amount": 10000, "currency": "ngn" }, "metadata": { "key": "value" }, "payment_options": { "return_url": "https://smart-glocal.com", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.327146Z", "capture": "2025-12-04T07:49:42.965552Z" } } }' ``` ### Sequence diagram ![](/img/docs/payments/opay/opay.png) ```plantuml @startuml OPay payment autonumber header OPay payments actor Customer participant Partner participant Smart_Glocal as SG Customer -> Partner: wants to make a payment Partner -> SG: sends ""session/create"" SG -> SG: creates a session SG --> Partner: sends 200 OK Partner -> SG: sends ""session/start/payment"" SG -> SG: starts the payment SG --> Partner: sends 200 OK SG -> Partner: sends ""ready_to_confirm"" webhook Partner --> SG: sends 200 OK Partner -> Partner: checks the details Partner -> SG: sends ""session/confirm"" SG --> Partner: sends 200 OK SG -> Partner: sends ""action_required"" Partner --> SG: sends 200 OK Partner -> Customer: redirects to OPay payment page Customer -> Customer: makes the payment SG -> SG: withdraws the funds SG -> Partner: sends ""payment_finished"" Partner --> SG: sends 200 OK Partner -> Customer: informs of the payment results @enduml ``` --- ## Pix payments in Brazil > Source: /docs/payments/apms/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. ## Making a one-time 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). >To make later [recurring payments](#rec_pix), send "recurrent": true in the payment_options object. Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_5666", "payment_details": { "type": "internet_banking", "internet_banking": { // highlight-next-line "type": "pix", // highlight-start "pix": { "name": "Name Surname", "email": "email@example.com", "document": "12333315123" // highlight-end } } }, "amount_details": { "amount": 8007, "currency": "brl" }, "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { // highlight-next-line "country_iso2": "BR" } }, "payment_options": { "return_url": "https://smart-glocal.com/", // highlight-next-line "recurrent": true } }' ``` Response example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "status": "ok", "session": { "id": "ps_5666", "status": "in_progress", "created_at": "2025-12-04T19:28:58.077701Z", "updated_at": "2025-12-04T19:29:23.216667Z", "acquiring_payments": [{ "id": "pm_566184419", "status": "in_progress", "created_at": "2025-12-04T19:29:23.217101Z", "customer": { "reference": "qwiqwi" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "pix", "pix": { "document": "12333315123", "name": "Name Surname", "email": "email@example.com" } } }, "amount_details": { "amount": 8007, "currency": "brl" }, "participant_details": { "sender": { "country_iso2": "BR" } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": true } }] } }' ``` 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "status": "ok", "session": { "id": "ps_5666", "status": "in_progress", "created_at": "2025-12-04T19:28:58.077701Z", "updated_at": "2025-12-04T19:29:23.216667Z", "acquiring_payments": [{ "id": "pm_566184419", "status": "pending", "created_at": "2025-12-04T19:29:23.217101Z", "customer": { "reference": "qwiqwi" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "pix", "pix": { "document": "12333315123", "name": "Name Surname", "email": "email@example.com" } } }, "amount_details": { "amount": 8007, "currency": "brl" }, "participant_details": { "sender": { "country_iso2": "BR" } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": true } }], "actions": { "confirm": "2025-12-04T07:48:28.275964Z" } } }' ``` 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/confirm \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_5666" }' ``` 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "status": "ok", "session": { "id": "ps_5666", "status": "in_progress", "created_at": "2025-12-04T07:48:28.296138Z", "updated_at": "2025-12-04T07:48:28.958891Z", "acquiring_payments": [{ "id": "pm_566184419", "status": "pending", "created_at": "2025-12-04T07:48:28.296138Z", "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { "country_iso2": "BR" } }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "pix", "pix": { "document": "12333315123", "name": "Name Surname", "email": "email@example.com" } } }, "amount_details": { "amount": 8007, "currency": "brl" }, "customer_interaction": { "type": "redirect", "redirect": { // highlight-next-line "url": "https://redirect-url-example.com/12345", "base_url": "https://redirect-url-example.com/12345", "method": "GET", "params": {} } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": true } }] } }' ``` 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. If you passed "recurrent": true, you will get a recurring token in the recurrent object. Webhook example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "status": "ok", "session": { "id": "ps_5666", "status": "accepted", "created_at": "2025-12-04T07:48:28.275964Z", "updated_at": "2025-12-04T07:49:43.022068Z", "acquiring_payments": [{ "id": "pm_566184419", "status": "succeeded", "created_at": "2025-12-04T07:48:28.296138Z", "finished_at": "2025-12-04T07:49:43.002789Z", "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { "country_iso2": "BR" } }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "pix", "pix": { "document": "12333315123", "name": "Name Surname", "email": "email@example.com" } } }, "amount_details": { "amount": 8007, "currency": "brl" }, "payment_options": { "return_url": "https://smart-glocal.com", "recurrent": true }, // highlight-start "recurrent": { "token": "6a6a29c4193a8e1049231e1497a3c5f180e120b20db81b39f53ec478029b53cf", "created_at": "2025-12-04T07:48:28.275964Z", "finished_at": "2035-12-04T07:48:28.275964Z", "is_active": true, "type": "recurrent_token" } // highlight-end }], "actions": { "confirm": "2025-12-04T07:48:28.327146Z", "capture": "2025-12-04T07:49:42.965552Z" } } }' ``` Sequence diagram ![](/img/docs/payments/pix.png) ```plantuml @startuml Pix payment autonumber header Pix payment actor Customer participant Partner participant Smart_Glocal as SG Customer -> Partner: wants to make a payment Partner -> SG: sends ""session/create"" SG -> SG: creates a session SG --> Partner: sends 200 OK Partner -> SG: sends ""session/start/payment"" SG -> SG: starts the payment SG --> Partner: sends 200 OK SG -> Partner: sends ""ready_to_confirm"" webhook Partner --> SG: sends 200 OK Partner -> Partner: checks the details Partner -> SG: sends ""session/confirm"" SG --> Partner: sends 200 OK SG -> Partner: sends ""action_required"" Partner --> SG: sends 200 OK alt Payment with a QR code Partner -> Customer: displays the QR code Customer -> Customer: reads the code \nand makes the payment end Partner -> Customer: forwards customer to issuer's app Customer -> Customer: makes the payment Customer -> Partner: returns by ""payment_options.return_url"" SG -> SG: withdraws the funds SG -> Partner: sends ""payment_finished"" Partner --> SG: sends 200 OK @enduml ``` ## Making a recurring Pix MIT payment Once you made a one-time payment with "recurrent": true and received a recurring token in the recurrent object, you can make recurring payments. To make a recurring payment, complete the steps above, but send the received token in the session/start/payment request instead of Pix details. #### Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_3230", // highlight-start "payment_details": { "type": "recurrent", "recurrent": { "token": "6a6a29c4193a8e1049231e1497a3c5f180e120b20db81b39f53ec478029b53cf" } }, // highlight-end "amount_details": { "amount": 10000, "currency": "brl" }, "customer": { "reference": "lucky" } }' ``` [Learn how to manage recurring tokens](/docs/payments/payment-recurring#managing-your-tokens) --- ## PromptPay payments in Thailand > Source: /docs/payments/apms/promptpay You can make local PromptPay payments in Thailand in Thai baht (THB). >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_promptpay in internet_banking.type - country_iso2 = TH in internet_banking.country_ewallet - the payer's full_name, email, and 13-digit Thai Identity Card in document 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_12345", "payment_details": { "type": "internet_banking", "internet_banking": { // highlight-start "type": "country_ewallet_promptpay", "country_ewallet": { "country_iso2": "TH" // highlight-end } } }, "amount_details": { "amount": 10000, "currency": "thb" }, "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { // highlight-start "full_name": "Name Surname", "email": "email@example.com", "document": "1234567890123" // highlight-end } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }' ``` Response example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2025-12-04T19:28:58.077701Z", "updated_at": "2025-12-04T19:29:23.216667Z", "acquiring_payments": [{ "id": "pm_12354", "status": "in_progress", "created_at": "2025-12-04T19:29:23.217101Z", "customer": { "reference": "qwiqwi" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_promptpay", "country_ewallet": { "country_iso2": "TH" } } }, "amount_details": { "amount": 10000, "currency": "thb" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "1234567890123" } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }] } }' ``` 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2025-12-04T19:28:58.077701Z", "updated_at": "2025-12-04T19:29:23.216667Z", "acquiring_payments": [{ "id": "pm_12354", "status": "pending", "created_at": "2025-12-04T19:29:23.217101Z", "customer": { "reference": "qwiqwi" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_promptpay", "country_ewallet": { "country_iso2": "TH" } } }, "amount_details": { "amount": 10000, "currency": "thb" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "1234567890123" } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.275964Z" } } }' ``` 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/confirm \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_12345" }' ``` 5. Wait for an [action_required](/docs/reference/webhooks/action-required) webhook. The customer_interaction.redirect.url parameter contains a link to the local payment method page. Webhook example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2025-12-04T07:48:28.296138Z", "updated_at": "2025-12-04T07:48:28.958891Z", "acquiring_payments": [{ "id": "pm_12354", "status": "pending", "created_at": "2025-12-04T07:48:28.296138Z", "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "1234567890123" } }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_promptpay", "country_ewallet": { "country_iso2": "TH" } } }, "amount_details": { "amount": 10000, "currency": "thb" }, "customer_interaction": { "type": "redirect", "redirect": { // highlight-next-line "url": "https://redirect-url-example.com/12345", "base_url": "https://redirect-url-example.com/12345", "method": "GET", "params": {} } }, "metadata": { "key": "value" }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.327146Z" } } }' ``` 5.1 Show the user the QR code on your page: 5.2 The user scans the QR code in an app that supports Thai QR code payments. 5.3 The user confirms the payment in the app. 6. After the user 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "status": "ok", "session": { "id": "ps_12345", "status": "accepted", "created_at": "2025-12-04T07:48:28.275964Z", "updated_at": "2025-12-04T07:49:43.022068Z", "acquiring_payments": [{ "id": "pm_12354", "status": "succeeded", "created_at": "2025-12-04T07:48:28.296138Z", "finished_at": "2025-12-04T07:49:43.002789Z", "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "1234567890123" } }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_promptpay", "country_ewallet": { "country_iso2": "TH" } } }, "amount_details": { "amount": 10000, "currency": "thb" }, "metadata": { "key": "value" }, "payment_options": { "return_url": "https://smart-glocal.com", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.327146Z", "capture": "2025-12-04T07:49:42.965552Z" } } }' ``` ### Sequence diagram ![](/img/docs/payments/promptpay/promptpay.png) ```plantuml @startuml PromptPay payment autonumber header PromptPay payments actor Customer participant Partner participant Smart_Glocal as SG Customer -> Partner: wants to make a payment Partner -> SG: sends ""session/create"" SG -> SG: creates a session SG --> Partner: sends 200 OK Partner -> SG: sends ""session/start/payment"" SG -> SG: starts the payment SG --> Partner: sends 200 OK SG -> Partner: sends ""ready_to_confirm"" webhook Partner --> SG: sends 200 OK Partner -> Partner: checks the details Partner -> SG: sends ""session/confirm"" SG --> Partner: sends 200 OK SG -> Partner: sends ""action_required"" Partner --> SG: sends 200 OK Partner -> Customer: displays QR code Customer -> Customer: makes the payment SG -> SG: withdraws the funds SG -> Partner: sends ""payment_finished"" Partner --> SG: sends 200 OK Partner -> Customer: informs of the payment results @enduml ``` --- ## TrueMoney payments in Thailand > Source: /docs/payments/apms/true-money You can make local TrueMoney payments in Thailand in Thai baht (THB). >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_truemoney in internet_banking.type - country_iso2 = TH in internet_banking.country_ewallet - the payer's full_name, email, and 13-digit Thai Identity Card in document 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_12345", "payment_details": { "type": "internet_banking", "internet_banking": { // highlight-start "type": "country_ewallet_truemoney", "country_ewallet": { "country_iso2": "TH" // highlight-end } } }, "amount_details": { "amount": 10000, "currency": "thb" }, "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { // highlight-start "full_name": "Name Surname", "email": "email@example.com", "document": "1234567890123" // highlight-end } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }' ``` Response example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2025-12-04T19:28:58.077701Z", "updated_at": "2025-12-04T19:29:23.216667Z", "acquiring_payments": [{ "id": "pm_12354", "status": "in_progress", "created_at": "2025-12-04T19:29:23.217101Z", "customer": { "reference": "qwiqwi" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_truemoney", "country_ewallet": { "country_iso2": "TH" } } }, "amount_details": { "amount": 10000, "currency": "thb" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "1234567890123" } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }] } }' ``` 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2025-12-04T19:28:58.077701Z", "updated_at": "2025-12-04T19:29:23.216667Z", "acquiring_payments": [{ "id": "pm_12354", "status": "pending", "created_at": "2025-12-04T19:29:23.217101Z", "customer": { "reference": "qwiqwi" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_truemoney", "country_ewallet": { "country_iso2": "TH" } } }, "amount_details": { "amount": 10000, "currency": "thb" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "1234567890123" } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.275964Z" } } }' ``` 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/confirm \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_12345" }' ``` 5. Wait for an [action_required](/docs/reference/webhooks/action-required) webhook. The customer_interaction.redirect.url parameter contains a link to the local payment method page. Webhook example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2025-12-04T07:48:28.296138Z", "updated_at": "2025-12-04T07:48:28.958891Z", "acquiring_payments": [{ "id": "pm_12354", "status": "pending", "created_at": "2025-12-04T07:48:28.296138Z", "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "1234567890123" } }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_truemoney", "country_ewallet": { "country_iso2": "TH" } } }, "amount_details": { "amount": 10000, "currency": "thb" }, "customer_interaction": { "type": "redirect", "redirect": { // highlight-next-line "url": "https://redirect-url-example.com/12345", "base_url": "https://redirect-url-example.com/12345", "method": "GET", "params": {} } }, "metadata": { "key": "value" }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.327146Z" } } }' ``` 5.1 When redirected, the user sees a payment page with a QR code. The payment page lifetime is 3 minutes: 5.2 The user opens the TrueMoney app and scans the QR code. 5.3 The user confirms the payment in the app. 5.4 The page shows the successful payment result. 6. After the user 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "status": "ok", "session": { "id": "ps_12345", "status": "accepted", "created_at": "2025-12-04T07:48:28.275964Z", "updated_at": "2025-12-04T07:49:43.022068Z", "acquiring_payments": [{ "id": "pm_12354", "status": "succeeded", "created_at": "2025-12-04T07:48:28.296138Z", "finished_at": "2025-12-04T07:49:43.002789Z", "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { "full_name": "Name Surname", "email": "email@example.com", "document": "1234567890123" } }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_truemoney", "country_ewallet": { "country_iso2": "TH" } } }, "amount_details": { "amount": 10000, "currency": "thb" }, "metadata": { "key": "value" }, "payment_options": { "return_url": "https://smart-glocal.com", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.327146Z", "capture": "2025-12-04T07:49:42.965552Z" } } }' ``` ### Sequence diagram ![](/img/docs/payments/truemoney/truemoney.png) ```plantuml @startuml TrueMoney payment autonumber header TrueMoney payments actor Customer participant Partner participant Smart_Glocal as SG Customer -> Partner: wants to make a payment Partner -> SG: sends ""session/create"" SG -> SG: creates a session SG --> Partner: sends 200 OK Partner -> SG: sends ""session/start/payment"" SG -> SG: starts the payment SG --> Partner: sends 200 OK SG -> Partner: sends ""ready_to_confirm"" webhook Partner --> SG: sends 200 OK Partner -> Partner: checks the details Partner -> SG: sends ""session/confirm"" SG --> Partner: sends 200 OK SG -> Partner: sends ""action_required"" Partner --> SG: sends 200 OK Partner -> Customer: redirects to TrueMoney payment page Customer -> Customer: makes the payment SG -> SG: withdraws the funds SG -> Partner: sends ""payment_finished"" Partner --> SG: sends 200 OK Partner -> Customer: informs of the payment results @enduml ``` --- ## VietQR payments in Vietnam > Source: /docs/payments/apms/vietqr You can make VietQR payments in Vietnam in Vietnamese dong (VND). >No recurring payments are available. ### 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 | VNID (9 to 13 digits) | ## 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_vietqr in internet_banking.type - country_iso2 in internet_banking.country_ewallet - the payer's full_name, email, and document 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_5666", "payment_details": { "type": "internet_banking", "internet_banking": { // highlight-start "type": "country_ewallet_vietqr", "country_ewallet": { "country_iso2": "VN" // highlight-end } } }, "amount_details": { "amount": 100000, "currency": "vnd" }, "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { // highlight-start "full_name": "Name Surname", "document": "12333315123", "email": "email@example.com" // highlight-end } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }' ``` Response example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "status": "ok", "session": { "id": "ps_5666", "status": "in_progress", "created_at": "2025-12-04T19:28:58.077701Z", "updated_at": "2025-12-04T19:29:23.216667Z", "acquiring_payments": [{ "id": "pm_12354", "status": "in_progress", "created_at": "2025-12-04T19:29:23.217101Z", "customer": { "reference": "qwiqwi" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_vietqr", "country_ewallet": { "country_iso2": "VN" } } }, "amount_details": { "amount": 100000, "currency": "vnd" }, "participant_details": { "sender": { "full_name": "Name Surname", "document": "12333315123", "email": "email@example.com" } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }] } }' ``` 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "status": "ok", "session": { "id": "ps_5666", "status": "in_progress", "created_at": "2025-12-04T19:28:58.077701Z", "updated_at": "2025-12-04T19:29:23.216667Z", "acquiring_payments": [{ "id": "pm_12354", "status": "pending", "created_at": "2025-12-04T19:29:23.217101Z", "customer": { "reference": "qwiqwi" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_vietqr", "country_ewallet": { "country_iso2": "VN" } } }, "amount_details": { "amount": 100000, "currency": "vnd" }, "participant_details": { "sender": { "full_name": "Name Surname", "document": "12333315123", "email": "email@example.com" } }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.275964Z" } } }' ``` 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/confirm \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_5666" }' ``` 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "status": "ok", "session": { "id": "ps_5666", "status": "in_progress", "created_at": "2025-12-04T07:48:28.296138Z", "updated_at": "2025-12-04T07:48:28.958891Z", "acquiring_payments": [{ "id": "pm_12354", "status": "pending", "created_at": "2025-12-04T07:48:28.296138Z", "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { "full_name": "Name Surname", "document": "12333315123", "email": "email@example.com" } }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_vietqr", "country_ewallet": { "country_iso2": "VN" } } }, "amount_details": { "amount": 100000, "currency": "vnd" }, "customer_interaction": { "type": "redirect", "redirect": { // highlight-next-line "url": "https://redirect-url-example.com/12345", "base_url": "https://redirect-url-example.com/12345", "method": "GET", "params": {} } }, "metadata": { "key": "value" }, "payment_options": { "return_url": "https://smart-glocal.com/", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.327146Z" } } }' ``` 5.1 The user redirected by the link from the webhook lands on a page like this: 5.2 The user selects a payment method and the QR code appears. 5.3 After the user completes the payment, a message on successful payment appears. 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "status": "ok", "session": { "id": "ps_5666", "status": "accepted", "created_at": "2025-12-04T07:48:28.275964Z", "updated_at": "2025-12-04T07:49:43.022068Z", "acquiring_payments": [{ "id": "pm_12354", "status": "succeeded", "created_at": "2025-12-04T07:48:28.296138Z", "finished_at": "2025-12-04T07:49:43.002789Z", "customer": { "reference": "qwiqwi" }, "participant_details": { "sender": { "full_name": "Name Surname", "document": "12333315123", "email": "email@example.com" } }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "country_ewallet_vietqr", "country_ewallet": { "country_iso2": "VN" } } }, "amount_details": { "amount": 100000, "currency": "vnd" }, "metadata": { "key": "value" }, "payment_options": { "return_url": "https://smart-glocal.com", "recurrent": false } }], "actions": { "confirm": "2025-12-04T07:48:28.327146Z", "capture": "2025-12-04T07:49:42.965552Z" } } }' ``` ### Sequence diagram ![](/img/docs/payments/vietqr/vietqr.png) ```plantuml @startuml VietQR payment autonumber header VietQR payments actor Customer participant Partner participant Smart_Glocal as SG Customer -> Partner: wants to make a payment Partner -> SG: sends ""session/create"" SG -> SG: creates a session SG --> Partner: sends 200 OK Partner -> SG: sends ""session/start/payment"" SG -> SG: starts the payment SG --> Partner: sends 200 OK SG -> Partner: sends ""ready_to_confirm"" webhook Partner --> SG: sends 200 OK Partner -> Partner: checks the details Partner -> SG: sends ""session/confirm"" SG --> Partner: sends 200 OK SG -> Partner: sends ""action_required"" Partner --> SG: sends 200 OK Partner -> Customer: displays the payment page Customer -> Customer: makes the payment SG -> SG: withdraws the funds SG -> Partner: sends ""payment_finished"" Partner --> SG: sends 200 OK Partner -> Customer: informs of the payment results @enduml ``` --- ## 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 complains 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. > >In the same object, pass return_url --- the URL to which the user is redirected after the payment is performed. This parameter is mandatory for payments made without our payment widget. #### Example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "32", "security_code": "087" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" }, "payment_options": { "recurrent": true, "return_url": "https://website.com" } }' ``` 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](/docs/reference/methods/token-method)). 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_info) 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_info) 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 four 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) ```plantuml @startuml MIT recurring payment autonumber header MIT recurring payment actor Customer participant Partner participant Smart_Glocal as SG participant ACS Partner -> Customer: requests consent Customer --> Partner: gives consent Partner -> SG: sends ""session/create"" SG -> SG: creates a session SG --> Partner: sends 200 OK Partner -> SG: sends ""session/start/payment"" with ""recurrent:true"" SG -> SG: starts the payment SG --> Partner: sends 200 OK SG -> Partner: sends ""ready_to_confirm"" webhook Partner --> SG: sends 200 OK Partner -> Partner: checks the details Partner -> SG: sends ""session/confirm"" SG --> Partner: sends 200 OK SG -> SG: checks if the card is \n involved in 3D Secure alt #faf1d7 The card is involved in 3d Secure SG -> Partner: sends ""action_required"" Partner --> SG: sends 200 OK Partner -> ACS: redirects the user for passing 3D Secure ACS -> SG: sends 3D Secure results end SG -> SG: withdraws the funds SG -> Partner: sends ""payment_finished"" with a recurrent object Partner --> SG: sends 200 OK @enduml ``` ![](/img/docs/recP_widget.png) ```plantuml @startuml MIT recurring payments with the widget autonumber header MIT recurring payments with the widget participant Partner participant Smart_Glocal as SG participant SG_Widget as sgw participant ACS Partner -> SG: sends ""session/create"" SG -> SG: creates a session SG --> Partner: sends 200 OK Partner -> SG: requests public token SG -> SG: creates a token SG --> Partner: sends 200 OK and token details Partner -> sgw: calls ""render()"" rnote over sgw The user interacts with the widget and checks the **I agree to recurring payments** checkbox endrnote sgw -> SG: initiates payment SG -> Partner: sends ""ready_to_confirm"" Partner --> SG: sends 200 OK Partner -> Partner: checks the details Partner -> SG: sends ""session/confirm"" SG --> Partner: sends 200 OK SG -> SG: checks if the card is \n involved in 3D Secure alt #faf1d7 The card is involved in 3d Secure SG -> sgw: sends data required for 3D Secure sgw -> ACS: redirects the user for passing 3D Secure ACS -> SG: sends 3D Secure results end SG -> SG: withdraws the funds SG -> Partner: sends ""payment_finished"" with a recurring token Partner --> SG: sends 200 OK SG -> sgw: sends payment details sgw -> sgw: shows payment status @enduml ``` --- ## 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 from the next step right away and skip it. 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_3230", "payment_details": { "type": "recurrent", "recurrent": { "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39", // highlight-next-line "initiator": "merchant" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" } }' ``` 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) ```plantuml @startuml MIT recurring payment autonumber header MIT recurring payment participant Partner participant Smart_Glocal as SG Partner -> SG: sends ""session/create"" SG -> SG: creates a session SG --> Partner: sends 200 OK Partner -> SG: sends ""session/start/payment"" with ""type: recurrent"" SG -> SG: starts the payment SG --> Partner: sends 200 OK SG -> Partner: sends ""ready_to_confirm"" webhook Partner --> SG: sends 200 OK Partner -> SG: sends ""session/confirm"" SG --> Partner: sends 200 OK SG -> SG: withdraws the funds SG -> Partner: sends ""payment_finished"" Partner --> SG: sends 200 OK @enduml ``` --- ## 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 from the next step right away and skip it. 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_3230", "payment_details": { "type": "recurrent", "recurrent": { "token": "token_value", // highlight-next-line "initiator": "client" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-next-line "return_url": "https://smart-glocal.com" } }' ``` 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference":"user@smart-glocal.com" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "usd" } } }, "customer_interaction": { "type": "redirect", // highlight-next-line "redirect": { "url": "https://smart-glocal.com?foo=bar", "base_url": "https://smart-glocal.com", "method": "GET", "qs": { "foo": "bar" }, "params": { "PaReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } } }] } }' ``` 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", // highlight-next-line "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference":"lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890" } }, "recurrent": { "token": "feda2b2106a2e8747bbdc4c9f53c7f5f6ab845ffa1b7cc68ca839720af99b3d1", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "is_active": true, "type": "recurrent_token" }, "amount_details": { "amount": 10000, "currency": "usd" } }] } }' ``` ### Sequence diagram of CIT recurring payments ![](/img/docs/cit_recurring_payment.png) ```plantuml @startuml CIT recurring payments autonumber header CIT recurring payments actor Customer participant Partner participant Smart_Glocal as SG participant ACS Customer -> Partner: requests recurring payments Partner -> SG: sends ""session/create"" SG -> SG: creates a session SG --> Partner: sends 200 OK Partner -> SG: sends ""session/start/payment"" SG -> SG: starts the payment SG --> Partner: sends 200 OK SG -> Partner: sends ""ready_to_confirm"" webhook Partner --> SG: sends 200 OK Partner -> Partner: checks the details Partner -> SG: sends ""session/confirm"" SG --> Partner: sends 200 OK SG -> Partner: sends ""action_required"" Partner --> SG: sends 200 OK Partner -> ACS: redirects the user for passing 3D Secure ACS -> SG: sends 3D Secure results SG -> SG: withdraws the funds SG -> Partner: sends ""payment_finished"" Partner --> SG: sends 200 OK @enduml ``` --- ## 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 ```json showLineNumbers { "chat_id": 123456789, "need_phone_number": true, "title": "*", "description": "*", "payload": "*", "provider_token": "0987654321:TEST", "currency": "USD", "prices": [{ "label": "Amount", "amount": 1000 }], "provider_data": { "email": "johnjohnson@example.com", "state": "TX", "city": "Dallas", "address_line": "Riot Ave", "full_name": "John Johnson", "postal_code": "129164", "country_iso2": "US", "country_iso3": "USA", "ipv4": "127.0.0.1" } } ``` 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 handling 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) ```plantuml @startuml Payment with Telegram bot autonumber header Payment with Telegram bot participant Partner participant Partner_Bot as PB participant Telegram participant Smart_Glocal as SG PB -> Telegram: sends ""sendinvoice"" Telegram --> PB: sends OK Telegram -> Telegram: renders the payment form and\nthe customer fills in the fields Telegram -> Telegram: the customer clicks ""Pay"" Telegram -> PB: sends ""PreCheckoutQuery"" PB --> Telegram: sends OK PB -> Telegram: sends ""answerPreCheckoutQuery"" Telegram --> PB: sends OK alt #faf1d7 3DS required Telegram -> Telegram: redirects the customer for 3DS SG -> Partner: sends ""action_required"" webhook Partner --> SG: sends OK end Telegram -> PB: sends the payment result SG -> Partner: sends ""payment_finished"" webhook Partner --> SG: sends OK @enduml ``` --- ## 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 | --- ## 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 | 108 | | **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** | 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) --- ## 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 | - | array | [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) | | payment_options |- |object |[Payment parameters](/docs/reference/objects#payment_options) | | metadata | - (mandatory for submerchants) | * | [Additional information](/docs/reference/objects#metadata) | | 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 payment 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 Amount details. | Name | Mandatory | Type | Description | | -------- | --------- | ------ | --------------------------------------------------------------------------------------------------------- | | amount | + | int | Amount in minor currency units, 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, upi | | global | - (mandatory for system_type = global) | object | [Recipient's bank account details](/docs/reference/objects#bank_account_global) | | ru | - (mandatory for system_type = ru) | object | [Recipient's bank account details](/docs/reference/objects#bank_account_ru) | | upi | - (mandatory for system_type = upi) | object | UPI details. Always: {} | ## 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 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/payments/payment-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 for type = redirect) | object | [User redirect data](/docs/reference/objects#redirect) | | inform | - (mandatory for 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) ## exchange_amounts Currency conversion details (see [Currency conversion with the widget](/docs/payments/conversion)). | Name | Mandatory | Type | Description | |---------------|-----------|--------|----------------------------------------------------------------------| | source | + | object | [Source amount](/docs/reference/objects#amount_details) | | destination | + | object | [Target amount](/docs/reference/objects#amount_details) | | rate | + | float | Applied exchange rate | | rate_source | + | string | Exchange rate source | | reserved_to | + | int | Time until which the exchange rate is reserved | ## 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, country_ewallet_momo, country_ewallet_opay, country_ewallet_promptpay, country_ewallet_truemoney, country_ewallet_vietqr | | pix | - (mandatory for type = pix) | object | [Payer's details](/docs/reference/objects#pix) | | country_ewallet | - (mandatory for type = country_ewallet and all country_ewallet_* types) | 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 | - (mandatory for [MoR](/docs/payments/mor)) | string | Product item category. Always: general | ## metadata This block may contain any additional information. May be a string, an integer, or an object. It is **mandatory** for transactions processed on behalf of submerchants or by a submerchant. In this case, pass the submerchant field. Any additional fields and their names are up to you --- the fields below are just an example. | Name | Mandatory | Type | Description | |------------------------|-----------|--------|----------------------------------| | submerchant | + |string | Any unique value, for example, a URL of the payment site | | merchant | - |string | Merchant ID or name | | merchant_order_id | - |string | Order number | | user_os | - |string | User's operating system | | user_location | - |string | User's country | | user_ip | - |string | User's IP | Examples ```json showLineNumbers { "metadata": { "merchant": "", "submerchant": "https://submerchant-site-url.com" } } ``` ```json showLineNumbers { "metadata": { "merchant": "", "submerchant": "https://t.me/Submerchant_Bot" } } ``` ```json showLineNumbers { "metadata": { "merchant": "", "submerchant": "Game name" } } ``` ```json showLineNumbers { "metadata": { "submerchant": "https://submerchant-site.com", "merchant_order_id": "123123", "user_os": "android", "user_location": "DE", "user_ip": "127.0.0.1" } } ``` ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/init/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "35", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" }, "metadata": { "submerchant": "https://submerchant-site-url.com", "merchant_order_id": "123123", "user_os": "android", "user_location": "DE" } }' ``` ## order Order details. | Name | Mandatory | Type | Description | | --------- | --------- | ------------------------------------------------------ | ------------------- | | order_id | + | string | Payment link identifier | | status | + | string | Payment link status. Options: success, failed | | reason | + | string | Failure reasons. Options: attempts_exhausted, canceled_by_merchant, timeout | ## 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 | - (mandatory for submerchants) | * | [Additional information](/docs/reference/objects#metadata) | | 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, bank_account | | 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) | | bank_account | - (mandatory for type = bank_account) | object | [Payer's account description](/docs/reference/objects#bank_account) | | 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 a token needs to be created for recurring payments | | 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 in lowercase. 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 | - (mandatory for submerchants) | * | [Additional information](/docs/reference/objects#metadata) | #### 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 Sender 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 | Sender 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 | ## 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 | | exchange_amounts | - | array | [Currency conversion details](/docs/reference/objects#exchange_amounts) | | 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 Transaction details. | 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 prefunding 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 capture timeout expired, the transaction was canceled | | 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 issuer 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 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 issuer 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 body 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) - [order_finished](/docs/reference/webhooks/order-finished) - [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 cancelled status. ### Parameters | Name | Mandatory | Type | Description | | ------- | --------- | ------------------------------------------------------------ | -------------------------------------- | | type | + | string | Webhook type: action_required | | session | + | object | [Payment session](/docs/reference/objects#payment_session) | ### Example ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_1313", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference":"user@sg.com" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890", "bin":"123456" } }, "amount_details": { "amount": 15000, "currency": "usd" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "customer_interaction": { "type": "redirect", "redirect": { "url": "https://website.com?foo=bar", "base_url": "https://website.com", "method": "POST", "qs": { "foo": "bar" }, "params": { "PaReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } } }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_1313", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference":"user@sg.com" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890", "bin":"123456" } }, "amount_details": { "amount": 15000, "currency": "usd" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "customer_interaction": { "type": "redirect", "redirect": { "url": "https://website.com?foo=bar", "base_url": "https://website.com", "method": "POST", "qs": { "foo": "bar" }, "params": { "PaReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } } }] } }' ``` --- ## order_finished > Source: /docs/reference/webhooks/order-finished ## order_finished You receive this webhook when an order is completed and the payment link is no longer valid. The webhook contains the order identifier and status. If the status is success, the payment was successful. If the status is failed, the payment failed for the reason returned in the webhook. ### Parameters | Name | Mandatory | Type | Description | | ------- | --------- | ------------------------------------------------------------ | --------------------------------------- | | type | + | string | Webhook type: order_finished | | order | + | object | [Order details](/docs/reference/objects#order) | ### Examples ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "order_finished", "order": { "order_id": "bYGR1PLkQ45Z7Vm9zJQx9G", "status": "success", "reason": null } }' ``` ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "order_finished", "order": { "order_id": "bYGR1PLkQ45Z7Vm9zJQx9G", "status": "failed", "reason": "timeout" // the time specified in the `active_to` field expired } }' ``` ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "order_finished", "order": { "order_id": "eiq1mbMiZF1ABIbL0ES0qK", "status": "failed", "reason": "attempts_exhausted" // the maximum number of attempts: 30 } }' ``` ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "order_finished", "order": { "order_id": "bTB6IoIqATD6OEdY4X1BVt", "status": "failed", "reason": "canceled_by_merchant" } }' ``` --- ## 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payments": [{ "id": "po_1313", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_method": { "type": "card", "card": { "last4": "7890", "brand": "visa", "bin":"123456" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_1313", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "7890", "brand": "visa", "bin":"123456" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payout_list": [{ "id": "po_1313", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payout_details": { "type": "card", "card": { "last4": "7890", "brand": "visa", "bin":"123456" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_1313", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "7890", "brand": "visa", "bin":"123456" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good" }] } }' ``` --- ## 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890", "bin":"123456" } }, "amount_details": { "amount": 1000, "currency": "usd" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "is_chargeback": true, "transaction_info": { "rrn": "425307614200", "auth_code": "123456" }, "amount_details": { "amount": 1000, "currency": "usd" } }] }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890", "bin":"123456" } }, "amount_details": { "amount": 1000, "currency": "usd" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "is_chargeback": true, "transaction_info": { "rrn": "425307614200", "auth_code": "123456" }, "amount_details": { "amount": 1000, "currency": "usd" } }] }] } }' ``` --- ## 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "capture", // highlight-next-line "acquiring_payments": [{ "id": "pm_1313", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "7890", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "capture", // highlight-next-line "payment_list": [{ "id": "pm_1313", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "7890", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } }' ``` --- ## 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 cancelled 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 ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", // highlight-next-line "payments": [{ "id": "po_1313", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_method": { "type": "card", "card": { "last4": "7890", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", // highlight-next-line "acquiring_payments": [{ "id": "pm_1313", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "7890", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", // highlight-next-line "payout_list": [{ "id": "po_1313", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payout_details": { "type": "card", "card": { "last4": "7890", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.com \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", // highlight-next-line "payment_list": [{ "id": "pm_1313", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "7890", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } }' ``` --- ## "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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/recurrent/disable \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "recurrent": { "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427" } }' ``` ### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|-----------------------------------------------------| | status | + | string | Status. Options: error, ok | | recurrent | - (returned if the request is successful) | object | [Token data](/docs/reference/objects#recurrent_info) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example ```json showLineNumbers { "recurrent": { "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427", "created_at": "2020-07-14T13:17:11+03:00", "finished_at": "2020-07-31T16:05:42+03:00", "is_active": false, "type": "recurrent_token" }, "status": "ok" } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` --- ## "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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/cancel \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "cancelled", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payments": [{ "id": "po_1313", "status": "failed", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_method": { "type": "card", "card": { "last4": "7890", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### Endpoint api/v2/session/cancel ### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | ------------------ | | session_id | + | string | Session identifier | Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v2/session/cancel \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "cancelled", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payout_list": [{ "id": "po_1313", "status": "failed", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [ { "email": "user@gmail.com" } ] }, // highlight-next-line "payout_details": { "type": "card", "card": { "last4": "7890", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` --- ## "session/capture" > Source: /docs/reference/methods/session-capture ## session/capture Send this request after you receive 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/capture \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_3230" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890" } }, "amount_details": { "amount": 10000, "currency": "usd" } }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### Endpoint api/v2/session/capture ### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | ------------------ | | session_id | + | string | Session identifier | Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v2/session/capture \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_3230" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890" } }, "amount_details": { "amount": 10000, "currency": "usd" } }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` --- ## "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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/confirm \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_1313", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "7890", "brand": "visa", "bin":"123456" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### Endpoint api/v2/session/confirm ### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | ------------------ | | session_id | + | string | Session identifier | Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v2/session/confirm \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_1313", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "7890", "brand": "visa", "bin":"123456" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` --- ## "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 minor currency units. To send 100 USD, specify 10000 | | items | - | array | [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](/docs/reference/objects#metadata) | >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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/create \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": { "submerchant": "https://submerchant-site-url.com" } }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "created", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z" } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### 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 minor currency units. To send 100 USD, specify 10000 | | items | - | array | [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](/docs/reference/objects#metadata) | >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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v2/session/create \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": { "submerchant": "https://submerchant-site-url.com" } }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "created", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z" } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` --- ## "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, 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 minor currency units. To send 100 USD, specify 10000 | | items | - | array | [Purchased product/service details](/docs/reference/objects#items) | | participant_details | - | object | [Information on the sender and recipient](/docs/reference/objects#participant_details) | | customer | + | object | [Customer's data in your system](/docs/reference/objects#customer) | | payment_options | - | object | [Additional payment parameters](/docs/reference/objects#payment_options) | | metadata | - (mandatory for submerchants) | * | [Any additional information](/docs/reference/objects#metadata). If the transaction is processed by a submerchant, specify the payment site: "metadata": {"merchant": "","submerchant": "https://website"} | Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/init/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "35", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" }, "metadata": { "submerchant": "https://submerchant-site-url.com", "merchant_order_id": "123123", "user_os": "android", "user_location": "DE" } }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_203", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "payment_options": { "return_url": "https://website.com" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### 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 minor currency units. To send 100 USD, specify 10000 | | items | - | array | [Purchased product/service details](/docs/reference/objects#items) | | participant_details | - | object | [Information on the sender and recipient](/docs/reference/objects#participant_details) | | customer | + | object | [Payer's data in your system](/docs/reference/objects#customer) | | payment_options | - | object | [Additional payment parameters](/docs/reference/objects#payment_options) | | metadata | - (mandatory for submerchants) | * | [Any additional information](/docs/reference/objects#metadata). If the transaction is processed by a submerchant, specify the payment site: "metadata": {"merchant": "","submerchant": "https://website"} | Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v2/session/init/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "35", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://website.com" }, "metadata": "good" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_203", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "payment_options": { "return_url": "https://website.com" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` --- ## "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, 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 minor currency units. 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 | - (mandatory for submerchants) | * | [Any additional information](/docs/reference/objects#metadata). If the transaction is processed by a submerchant, specify the payment site: "metadata": {"merchant": "","submerchant": "https://website"} | Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "payment_method": { "type": "bank_account", "bank_account": { "system_type": "global", "global": { "iban": "NUMBER_VALUE", "description": "purpose of remittance" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "participant_details": { "recipient": { "bank_name": "All Banks Belgium / EUR / Payment System: SEPA", "currency": "eur", "country_iso3": "BEL", "first_name": "John", "last_name": "Johnson" }, "sender": { "company_name": "Company name", "registration_number": "1234567890", "country_iso3": "USA", "code": "1234567890" } }, "metadata": "good" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payments": [{ "id": "po_1313", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_method": { "type": "bank_account", "bank_account": { "system_type": "global", "global": { "iban": "NUMBER_VALUE", "description": "purpose of remittance" } } }, "participant_details": { "recipient": { "bank_name": "All Banks Belgium / EUR / Payment System: SEPA", "currency": "eur", "country_iso3": "BEL", "first_name": "John", "last_name": "Johnson" }, "sender": { "company_name": "Company name", "registration_number": "1234567890", "country_iso3": "USA", "code": "1234567890" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### 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 minor currency units. 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 | - (mandatory for submerchants) | * | [Any additional information](/docs/reference/objects#metadata). If the transaction is processed by a submerchant, specify the payment site: "metadata": {"merchant": "","submerchant": "https://website"} | Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v2/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "payout_details": { "type": "bank_account", "bank_account": { "system_type": "global", "global": { "iban": "NUMBER_VALUE", "description": "purpose of remittance" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "participant_details": { "recipient": { "bank_name": "All Banks Belgium / EUR / Payment System: SEPA", "currency": "eur", "country_iso3": "BEL", "first_name": "John", "last_name": "Johnson" }, "sender": { "company_name": "Company name", "registration_number": "1234567890", "country_iso3": "USA", "code": "1234567890" } }, "metadata": "good" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payout_list": [{ "id": "po_1313", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payout_details": { "type": "bank_account", "bank_account": { "system_type": "global", "global": { "iban": "NUMBER_VALUE", "description": "purpose of remittance" } } }, "participant_details": { "recipient": { "bank_name": "All Banks Belgium / EUR / Payment System: SEPA", "currency": "eur", "country_iso3": "BEL", "first_name": "John", "last_name": "Johnson" }, "sender": { "company_name": "Company name", "registration_number": "1234567890", "country_iso3": "USA", "code": "1234567890" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` --- ## "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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/refund \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_3230" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "usd" } }] }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v2/session/refund \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id":"ps_3230" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "7890" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "usd" } }] }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` --- ## "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 minor currency units. To send 100 USD, specify 10000 | | items | - | array | [Purchased product/service details](/docs/reference/objects#items) | | customer | - | object | [Payer'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 | - (mandatory for submerchants) | * | [Any additional information](/docs/reference/objects#metadata). If the transaction is processed by a submerchant, specify the payment site: "metadata": {"merchant": "","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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "35", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" }, "metadata": "good" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_1313", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "last4": "7890", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### 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 minor currency units. To send 100 USD, specify 10000 | | items | - | array | [Purchased product/service details](/docs/reference/objects#items) | | customer | - | object | [Payer'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 | - (mandatory for submerchants) | * | [Any additional information](/docs/reference/objects#metadata). If the transaction is processed by a submerchant, specify the payment site: "metadata": {"merchant": "","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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v2/session/start/payment \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "35", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "customer": { "reference": "lucky" }, "metadata": "good" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_1313", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "last4": "7890", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` --- ## "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 in the minor units of the currency](/docs/reference/objects#amount_details) | | 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 | - (mandatory for submerchants) | * | [Any additional information](/docs/reference/objects#metadata). If the transaction is processed by a submerchant, specify the payment site: "metadata": {"merchant": "","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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/start/payout \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", // highlight-next-line "payment_method": { "type": "bank_account", "bank_account": { "system_type": "global", "global": { "iban": "NUMBER_VALUE", "description": "purpose of remittance" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "participant_details": { "recipient": { "bank_name": "All Banks Belgium / EUR / Payment System: SEPA", "currency": "eur", "country_iso3": "BEL", "first_name": "John", "last_name": "Johnson" }, "sender": { "company_name": "Company name", "registration_number": "1234567890", "country_iso3": "USA", "code": "1234567890" } }, "metadata": "good" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payments": [{ "id": "po_1313", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_method": { "type": "bank_account", "bank_account": { "system_type": "global", "global": { "iban": "NUMBER_VALUE", "description": "purpose of remittance" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "participant_details": { "recipient": { "bank_name": "All Banks Belgium / EUR / Payment System: SEPA", "currency": "eur", "country_iso3": "BEL", "first_name": "John", "last_name": "Johnson" }, "sender": { "company_name": "Company name", "registration_number": "1234567890", "country_iso3": "USA", "code": "1234567890" } }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### 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 in the minor units of the currency](/docs/reference/objects#amount_details) | | 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 | - (mandatory for submerchants) | * | [Any additional information](/docs/reference/objects#metadata). If the transaction is processed by a submerchant, specify the payment site: "metadata": {"merchant": "","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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v2/session/start/payout \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", // highlight-next-line "payout_details": { "type": "bank_account", "bank_account": { "system_type": "global", "global": { "iban": "NUMBER_VALUE", "description": "purpose of remittance" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "participant_details": { "recipient": { "bank_name": "All Banks Belgium / EUR / Payment System: SEPA", "currency": "eur", "country_iso3": "BEL", "first_name": "John", "last_name": "Johnson" }, "sender": { "company_name": "Company name", "registration_number": "1234567890", "country_iso3": "USA", "code": "1234567890" } }, "metadata": "good" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", // highlight-next-line "payout_list": [{ "id": "po_1313", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payout_details": { "type": "bank_account", "bank_account": { "system_type": "global", "global": { "iban": "NUMBER_VALUE", "description": "purpose of remittance" } } }, "amount_details": { "amount": 10000, "currency": "usd" }, "participant_details": { "recipient": { "bank_name": "All Banks Belgium / EUR / Payment System: SEPA", "currency": "eur", "country_iso3": "BEL", "first_name": "John", "last_name": "Johnson" }, "sender": { "company_name": "Company name", "registration_number": "1234567890", "country_iso3": "USA", "code": "1234567890" } }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` --- ## "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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/session/status \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", // highlight-next-line "payments": [{ "id": "po_1313", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_method": { "type": "card", "card": { "last4": "7890", "brand": "visa", "bin":"123456" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### Endpoint api/v2/session/status ### Request parameters | Name | Mandatory | Type | Description | | ---------- | --------- | ------ | -------------------------- | | session_id | + | string | Payment session identifier | Request example ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v2/session/status \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ### 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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "next_action": "confirm", // highlight-next-line "payout_list": [{ "id": "po_1313", "status": "pending", "created_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payout_details": { "type": "card", "card": { "last4": "7890", "brand": "visa", "bin":"123456" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good" }] } } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` --- ## 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. ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/token \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "tokenize_widget": { "access": true, "locale": "en" } }' ``` 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. ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/token \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "acquiring_widget": { "session_id": "ps_123456", "locale":"en", // highlight-next-line "show_recurrent_checkbox": true } }' ``` Get a token for the payment form for money transfers. ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/token \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-SUBMERCHANT: submerchant ID' \ -d '{ "fps_no_account_widget": { "session_id": "ps_123456" } }' ``` ### 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 ```json showLineNumbers { "status": "ok", "public_token": "e065c2f1328e74156a883c00e210a4b1b1451782bbfdd18ae8d05715e05d8548" } ``` Unsuccessful response example ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` --- ## "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. ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/token/info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "card_number_hash (token)" } } }' ``` Send a public token to get information about it. ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/token/info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "public_token", "public_token": { "token": "your_token" } }' ``` Send a token for recurring payments/payouts to get information about it. ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/token/info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "recurrent_token", "recurrent_token": { "token": "your_token" } }' ``` ### 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 ```json showLineNumbers { "status": "ok", "info": { "number_hash": "card_number_hash", "brand": "visa", "last4": "7890", "type": "card" } } ``` ```json showLineNumbers { "status": "ok", "info": { "token": "your_token", "created_at": "2021-03-17T14:10:56+03:00", "finished_at": "2021-03-18T14:10:56+03:00", "is_active": true, "type": "public_token" } } ``` ```json showLineNumbers { "status": "ok", "info": { "token": "your_token", "created_at": "2021-03-17T14:19:05+03:00", "finished_at": "2021-04-17T14:19:05+03:00", "is_active": true, "type": "recurrent_token" } } ``` Unsuccessful response example ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` --- ## "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 prefunding balance. >The amount is returned in minor currency units. 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 ```json showLineNumbers curl -X POST \ https://demo.smart-glocal.com/api/v1/wallet/balance \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_datetime":"2024-04-10T19:53:00+03:00" }' ``` ### Response parameters | Name | Mandatory | Type | Description | | ------- | --------- | ------------------------------------------------------------ | ------------------------------------------------- | | status | + | string | Status. Options: error, ok | | wallets | - | array | [List of wallet accounts available in Smart Glocal](/docs/reference/objects#wallet_details) | | error | - | object | [Error description](/docs/reference/objects#error) | Successful response example ```json showLineNumbers { "status": "ok", "wallets": [{ "id": "310", "amount_details": { "amount": 13000, "currency": "usd" } }] } ``` Unsuccessful response example ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ---