Payment widget integration with public key
This integration option is designed for the merchants who don't use backend development.
Info
Pay attention that the public key is potentially visible to the customer (for example, using the developer tools in the browser). To prevent fraud, it is neccessary to check all the parameters in the webhook notification before assigning the received status to the transaction. Below are the parameters that require special attention:
amount
,currency
,test
,tracking_id
Info
If the merchant has an opportunity to send a payment token request, it is recommnded to use the integration option with the payment token. The token request is made using the secret key for authorization which makes it impossible for the customer to change the payment parameters.
To make the UnonaPay payment widget appear to your customers on your website, follow the steps below:
-
Install the widget script.
To make the widget send requests, run the following script on your website:
<script type="text/javascript" src="https://js.unonapay.com/widget/be_gateway.js"></script>
-
Create the payment widget.
Register a function to generate the necessary parameters for the
BeGateway
constructor object, and to call out thecreateWidget
method. The payment is considered as successfully completed only after you receive the automatic payment notification.<script type="text/javascript"> this.payment = function() { var params ={ checkout_url: "https://checkout.unonapay.com", fromWebview: true, checkout: { iframe: true, test: true, transaction_type: "payment", public_key: "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA48od3W1P+xXvUMieH+WQ3koeL8HkweUd51Yt3l/VoHEkI4n7Rzaa5sA+YBBI/57YciRVnFFHwhOA6pLvfJXvyeB9EKpyaBaDT3xA1izuwybI3I93JVyplC4c8RryGyRrkaT7eUf6gZpjvn31otDj1HMQqRdiHFoNZuxxxVSAHUeCy4g+H6DbXm79dHtb3XLMSvmkzkLsQgWhKxr//BaTbItPWAqYYS+xgeNU8KnkRSS5bVzmYQrbW9CUPI4vMcFmJXc8Pg+Pn80ivavRLA9yXrig1cK3F3cIHcrJDBZWICJlGNxd6vrivX6AEQQfABHRlJRfMEVA252u5/swqAI/AQIDAQAB", order: { amount: 100, currency: "EUR", description: "Payment description", tracking_id: "my_transaction_id" }, }, closeWidget: function(status) { // possible values of status variable // successful - transaction is successful // failed - transaction is declined // pending - awaiting transaction confirmation // redirected - customer is redirected to external the payment method system // error - error in input paras/network error/etc // null - payment widget is closed console.debug('close widget callback') } }; new BeGateway(params).createWidget(); }; </script>
-
Call the created function.
Register the call of the above created function to some event, for example, to the “Pay” link click.
<a onclick="payment()" href="#">Pay</a>
Widget parameters
Parameter | Type | Description |
---|---|---|
checkout_url * required |
string | https://checkout.unonapay.com |
fromWebview | boolean | Set this parameter to true if you want the payment widget to open on payment initialization in a WebView (for example, within a web application). If this parameter is not provided, or it is set to false , initializing the payment will open the payment page instead. |
checkout | object | |
transaction_type * required |
string | A type of transaction or request that will be sent to gateway. Possible values: authorization ;payment ;tokenization ;charge (for the charge request). |
attempts | integer | A number of payment attempts. The default is 1 . |
dynamic_billing_descriptor | string | Dynamic billing descriptor. |
public_key * conditionally required |
string | Shop public key. Required if the token parameter is not sent. When using this method to launch the widget be sure to check the payment details in automatic notification and only then change the payment status to the received. |
test | boolean | Set to true for a test transaction. Otherwise, false (default). |
iframe | boolean | When the value is true , if possible, open transitions to external services inside the widget. By default, false . |
order | object | |
amount * required |
integer | A payment amount in minimal currency units, for example $32.45 must be sent as 3245. |
currency * required |
string | A transaction currency in the ISO-4217 alpha-3 code format. For example, USD . |
description * required |
string | Order description. |
tracking_id | string | The ID of transaction or order in your system. It is recommended to use unique value for each transaction |
expired_at | string | Date and time till which a payment can be done. By default a payment must be done within 24 hours upon a payment token creation. Format (ISO 8601): YYYY-MM-DDThh:mm:ssTZD, where YYYY – year (for example 2019), MM – month (for example 02), DD – day (for example 09), hh – hours (for example 18), mm – minutes (for example 20), ss – seconds (for example 45), TZD – time zone (+hh:mm или –hh:mm). |
additional_data | object | A section contains a detailed information about the payment |
receipt_text | array | Text, that will be added to client's mail and will be showed on success result page. Submit it as an array of strings, for example ["First line", "Second line"] |
contract | array | An array, consisting of elements:recurring - UnonaPay returns a card token to use it in subsequent charges without to enter a card data again. Customer agrees to be charged regularly, but initially the customer must make a payment with full card data including CVC/CVV code and pass 3-D Secure verification;oneclick - UnonaPay returns a card token to use it in the one-click payment scheme. It means UnonaPay will open a payment widget with pre-filled card data and customer will be forced to enter CVC/CVV code and pass 3-D Secure verification to complete payment;credit - UnonaPay returns a card token to use it for a payout;save_card - returns an information, that the customer has turned save card toggle to the active state. Used in addition to recurring , oneclick and credit parameters. Conditions of usage: 1. Parameter save_card_toggle.customer_contract is true 2. Customer has turned save card toggle to the active state. |
avs_cvc_verification | object | AVS/CVC verification |
card_on_file | object | It sets flags submitted to a payment network why and what you charged a previously saved card for. If the parameter is not submitted, default values of initiator and type are in use. |
initiator | string | merchant - (default) merchant initiated a card charge (for instance, for a car ride service)customer - customer initiated a card charge (for instance, customer confirmed an order and wanted to pay by a saved card) |
type | string | Used only in case additional_data.card_on_file.initiator is merchant . delayed_charge - (default) delayed charge posted to a cardincrement - merchant wants to charge additional amount above initially paid order (for instance, in case of upsale)resubmission - merchant wants to resubmit a transaction due to fail with a previous charge (for instance, no money on a card)reauthorization - merchant wants to refresh previously authorized amount (for instance, to continue to hold a money reserve on a card for future charges)no_show - merchant wants to charge a card when customer didn't come (for instance, no visit to a hotel) |
settings | object | |
save_card_toggle | object | A section for configuring the save card toggle. |
display | boolean | If the parameter is true , the save card toggle will be displayed on the widget. This parameter has greater priority, than Display save card toggle on payment page parameter in a shop settings in the Merchant back office. By default set to true |
customer_contract | boolean | true - when the customer has turned save card toggle to the active state, he gives a legal agreement for storage card datа by Merchant and use this agreement in the additional_data.contract . false - when the customer has turned save card toggle in the active state, he gives a legal agreement to store card only for selecting on the payment widget. By default set to false |
text | string | The parameter replaces the standard toggle name Save card to any Merchant text |
hint | string | hint text, described why the save card option is needed. |
another_card_toggle | object | A section for configuring the another card toggle. |
display | boolean | If the parameter is true , the toggle Рay with another card will be displayed on the widget. This parameter has greater priority, than Hide another card toggle on payment page parameter in a shop settings in the Merchant back office. By default set to true |
return_url | string | URL to return Customer to after transaction was complete. If not set, then only closeWidget function is called. If set, then both success_url and decline_url are ignored. |
success_url | string | URL to return Customer to if a transaction was successful. |
decline_url | string | URL to return Customer to if a transaction was declined by bank. |
fail_url | string | URL to return Customer to if a transaction failed (due to an error, exception and etc.). To check the status and a failure reason, send a status query request with the payment token. |
cancel_url | string | URL to return Customer to if Customer cancels a transaction. |
verification_url | string | URL where transaction verification request will be posted to. The verification request format equals to a transaction response format. |
notification_url | string | URL where notifications about the transaction will be posted to |
auto_return | string | After a transaction completes, UnonaPay shows a transaction result page for specified number of seconds and then automatically returns Customer to one of your return URLs. If the parameter value is 0 , then Customer will be automatically redirected without showing UnonaPay transaction result page. |
button_text | string | Customize the payment button text. Note: {amount} can be used as a placeholder to show transaction amount within the customized text |
button_next_text | string | Customize the payment result page button text |
language | string | Checkout page locale. English (en ) is set by default. Possible values of language parameter. |
customer_fields | object | It controls the input fields for customer details shown at the payment widget. |
read_only | array | It is an array which may consist of the values email , first_name , last_name , address , city , state , zip , phone , country , birth_date , taxpayer_id . Fields for customer's data indicated in the array will be disabled at the payment widget. If email exists in the array then it must present in the customer section below and it can't be empty. |
visible | array | It is an array which may consist of the values email , first_name , last_name , address , city , state , zip , phone , country and birth_date , taxpayer_id . Fields for customer's data indicated in the array will be displayed at the payment widget. |
credit_card_fields | object | It controls the automatic filling of the cardholder name on the payment widget. |
holder | string | Cardholder name for automatic filling on the payment widget. |
read_only | array | It is an array which may consist only holder value. Blocks editing of the selected field. |
customer * conditionally required |
object | A section of the customer information. Contact Tech Support Team to check what section parameters are required. |
string | Customer email | |
first_name | string | The customer's first name. |
last_name | string | The customer's last name. |
address | string | The customer's billing address. |
city | string | The customer's billing city. |
state | string | The customer's two-letter billing state only if the billing address country is US or CA . |
zip | string | The customer's billing ZIP or postal code. |
country | string | The customer's billing country in ISO 3166-1 alpha-2 format. |
phone | string | The customer's phone number. |
birth_date | string | The customer's birth date in ISO 8601 YYYY-MM-DD format. |
taxpayer_id | string | The customer's taxpayer ID. |
payment_method | object | A section contains information about which payment methods are available to the customer in order to make a payment, as well as the parameters necessary to initialize each payment method. If not submitted, all active payment methods are available by default. |
types | array | An array of available payment methods to enable on the payment widget. Possible values:credit_card - bank card paymentfor the remaining values of the array, see the section alternative payment methods for the value of the parameter type .If the listed payment methods require additional parameters, then create objects with the name from type and internal parameters from the alternative payment methods section.For example, for a payment method type apm with the parameter channel , send such an object:apm : { channel: "ONLINE" } Note! Apple Pay, Google Pay and Samsung Pay are displayed on the widget depending on the client's device and browser types. See more here. |
excluded_types | array | An array of the payment types that will be excluded from the available payment methods on the payment page. If both payment_method.types and payment_method.excluded_types are sent in the request, the information from payment_method.types will be applied and payment_method.excluded_types will be ignored. |
credit_card | object | |
token | string | Card token. The tokenized data will be displayed on the payment widget. |
travel | object | Travel related data. |
airline | object | The section contains airline ticket addendum data. |
agency_code | string | IATA agency code, for example 03 . |
agency_name | string | Agency name who sold the ticket, for example Corel travel . |
ticket_number | string | 14-digit ticket number. Should contain 3-digit ticketing code, 4-digit form number, 6-digit serial number, and check digit, for example 390 5241 025377 1 . |
booking_number | string | For example, DKZVUA . |
restricted_ticked_indicator | string | If the ticket can be returned, the field value is 0 , otherwise it is 1 . |
legs | array | An optional array of travel legs. Every legs consists of: |
airline_code | string | 2-letter IATA code, for example B2 . |
stop_over_code | string | IATA stopover code. If a traveler stays in the originating city more than 24h, then set the field value to O or left it empty. If the originating airport is transit airport, then set the field value to X . |
flight_number | string | For example, A3 971 . |
departure_date_time | string | For example, 2014-05-26T05:15:00 . |
arrival_date_time | string | For example, 2014-05-26T07:30:00 . |
originating_country | string | For example, RU . |
originating_city | string | For example, Moscow . |
originating_airport_code | string | 3-letter IATA code, for example DME . |
destination_country | string | For example, Greece . |
destination_city | string | For example, Athens . |
destination_airport_code | string | 3-letter IATA code, for example ATH . |
coupon | string | Coupon number if it was applied. |
class | string | Class flight, 1-letter IATA code. Example, C . |
passengers | array | List of passengers where every list item consists of |
first_name | string | First name of passenger, for example KONSTANTIN . |
last_name | string | Last name of passenger, for example IVANOV . |