Tokenization
The request is used to get a bank card token along with the 3-D Secure verification details and then to use the token to submit either a payment or an authorization transaction.
As a result of a tokenization transaction, money isn't withdrawn from the card account. Use the received token to send a payment or authorization request.
Request
To get a card tokenized, send a POST
request to https://gateway.unonapay.com/transactions/tokenizations
with the following parameters:
Parameter | Type | Description |
---|---|---|
amount * required |
bigInteger | A transaction amount in minimal currency units, for example, $32.45 must be sent as 3245 . |
currency * required |
string | Currency in ISO-4217 format, for example, USD . |
description * required |
string (255) | The short description of the order. |
tracking_id | string (255) | The ID of your transaction or order. Please, use unique values in order to get the correct transaction information in the response to the query request. Otherwise, you will get the first transaction that we will find with the matching tracking_id . Can be multiple values separated with semicolons. For example, "cbe59142-90af-4aea-b5a5-5bf3f66cf3da;f7883cb9-0e26-43a7-beb7-4027cb55d1a6;4a6a89d5-6950-400f" . If multiple values are sent in the request, the transaction search in the back office system can be performed by any of them. |
duplicate_check | boolean | The boolean parameter controls whether the payment gateway will do a duplicate check of the received requests to tokenize a card. By default, it is true and duplicate requests with the same amount and number sent within 30 seconds after the original request will be rejected. |
dynamic_billing_descriptor | string | A dynamic billing descriptor. |
language | string | A language of your checkout page or customer. If the parameter is set and transaction notification emails to customers are enabled, UnonaPay will dispatch those emails in language locale. English (en ) is set by default. Possible values of language parameter. |
notification_url | string | The URL where the webhook notification about a transaction will be posted. The notification request format is the same as the transaction response format. |
verification_url | string | The URL where the transaction verification request will be posted. The verification request format is the same as the transaction response format. |
return_url * conditionally required |
string | The URL on the merchant's website to which UnonaPay will redirect the customer once they complete 3-D verification. Required, if your merchant account is 3-D Secure enabled. |
test | boolean | If set to true , the transaction will be a test one. By default, false . |
credit_card | object | |
number * required |
string | The card number. The length is between 12 and 19 digits. |
verification_value * conditionally required |
string | 3- or 4-digit security code (called CVC2, CVV2 or CID depending on the credit card brand). The parameter can be required depending on the shop settings and acquirer requirements. |
holder * conditionally required |
string (35) | The cardholder name as it appears on the card. The parameter is optional in the UnonaPay system but can be required by the acquirer. |
exp_month * required |
string (2) | Card expiration month. Must be one or two digits (for example, 01). |
exp_year * required |
string (4) | Card expiration year. Must be 4 digits (for example, 2026). |
skip_three_d_secure_verification | boolean | The parameter enables the option for the customer to skip the 3-D Secure verification check. If true , UnonaPay doesn't launch the 3-D Secure verification. By default, false .The force_three_d_secure_verification parameter overrides the skip_three_d_secure_verification parameter, if both are set to true .Contact the Tech Support Team to check if you can apply this parameter. Overridden by Smart Routing rules with Skip 3ds or Force 3ds actions. |
force_three_d_secure_verification | boolean | The parameter enables the option to make the 3-D Secure verification check mandatory for the customer. If true , UnonaPay forces the 3-D Secure verification. By default, false .The force_three_d_secure_verification parameter overrides the skip_three_d_secure_verification parameter, if both are set to true .Contact the Tech Support Team to check if you can apply this parameter. Overridden by Smart Routing rules with Skip 3ds or Force 3ds actions. |
three_d_secure | object | A section with the settings to apply the advanced scenario of payment processing with 3-D Secure 2.0 verification. |
advanced | boolean | Set to true to apply the advanced scenario. Otherwise, set to false . |
additional_data | object | A section with additional transaction data. |
receipt_text | array | A text that will be added to the customer's email. 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 be used in subsequent charges without entering the 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 oneclick payment scheme. It means UnonaPay will open a payment page with the prefilled card data and customer will be forced to enter CVC/CVV code and pass 3-D Secure verification to complete the payment.credit - UnonaPay returns a card token to be used for a payout. |
customer * conditionally required |
object | A section of the customer information. Ask the Tech Support Team whether your acquirer requires any of the section parameters. |
ip * conditionally required |
string | The customer's IP address. |
email * conditionally required |
string | The customer's email. |
device_id * conditionally required |
string | The customer's device ID (desktop, smartphone, etc.). |
birth_date * conditionally required |
string | The customer's date of birth in the ISO 8601 format (YYYY-MM-DD ). |
billing_address | object | A section of the customer's address details. Contact the Tech Support Team to check if your acquirer requires any of the section parameters. |
first_name * conditionally required |
string (30) | The customer's first name. |
last_name * conditionally required |
string (30) | The customer's last name. |
country * conditionally required |
string | The customer's billing country in ISO 3166-1 Alpha-2 format. |
city * conditionally required |
string (60) | The customer's billing city. |
state * conditionally required |
string | The customer's two-letter billing state only if the billing address country is US or CA . |
zip * conditionally required |
string | The customer's billing ZIP or postal code. If country=US , zip format must be NNNNN or NNNNN-NNNN. |
address * conditionally required |
string (255) | The customer's billing address. |
phone * conditionally required |
string (100) | The customer's phone number. |
travel | object | An optional section with travel related data. |
airline | object | The section with airline ticket data. |
agency_code | string | IATA agency code, for example, 03 . |
agency_name | string | Name of the agency that sold the ticket, for example, Coral 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 leg 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 leave it empty. If the originating airport is a 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. For example, C . |
passengers | array | List of passengers where every list item consists of |
first_name | string | First name of the passenger, for example, KONSTANTIN . |
last_name | string | Last name of the passenger, for example, IVANOV . |
Example of the request
{
"request":{
"amount":100,
"currency":"USD",
"description":"Test transaction",
"tracking_id":"your_uniq_number",
"language":"en",
"billing_address":{
"first_name":"John",
"last_name":"Doe",
"country":"US",
"city":"Denver",
"state":"CO",
"zip":"96002",
"address":"1st Street"
},
"credit_card":{
"number":"4200000000000000",
"verification_value":"123",
"holder":"John Doe",
"exp_month":"05",
"exp_year":"2026"
},
"customer":{
"ip":"127.0.0.1",
"email":"john@example.com"
}
}
}
Response
In the transaction section response parameters replicate request parameters except the additional ones:
Parameter | Type | Description |
---|---|---|
transaction | object | |
uid * required |
string | A UID of the processed transaction. |
status * required |
string | A status of the processed transaction. |
message * required |
string | A processing result message. |
tracking_id * required |
string | The tracking_id parameter value sent in the transaction request. |
language * required |
string | The language parameter value sent in a transaction request or en if the parameter was omitted. |
type * required |
string | A transaction type. |
payment_method_type * required |
string | A payment method used to complete the transaction. Possible values: credit_card . |
credit_card | object | |
brand * required |
string | The detected card brand. |
product * required |
string | A card product type code. |
last_4 * required |
string | The last 4 digits of the card. |
first_1 * required |
string | The first digit of the card. |
bin * required |
string (6) | 6-digit bank identification number (BIN). The first 6 digits of the card number. |
bin_8 * required |
string (8) | 8-digit bank identification number (BIN). The first 8 digits of the card number. The value is returned for Visa, MasterCard, Maestro cards and the corresponding co-branded cards. Otherwise, null is returned. |
issuer_country * required |
string (2) | The country of the card issuing bank in ISO 3166-1 Alpha-2 format. |
issuer_name * required |
string | The name of the card issuing bank. |
stamp * required |
string | The card hash. It is constant even if either the expiration date or the cardholder is changed. |
token * required |
string | The card token. Store the token and charge returning customers or run recurring charges without customers' billing details. The token lets you save the customer's details and charge them whenever they make new purchases, or you renew their services. |
three_d_secure_verification | object | A section with 3-D Secure verification results. |
tokenization | object | |
message * required |
string | A tokenization result message. |
status * required |
string | A tokenization status. Possible values: successful ,failed . |
additional_data | object | A section of detailed information about the payment. |
receipt_text | array | A text that will be added to the customer email. |
smart_routing_verification | object | A section of parameters of Smart Routing verification results. |
status | string | Smart Routing check status for the transaction. |
Example of the response
{
"transaction": {
"uid": "e89abc1a-1d18-4d0f-83a1-7009b333dce0",
"status": "successful",
"amount": 492,
"currency": "EUR",
"description": "Test transaction",
"type": "tokenization",
"payment_method_type": "credit_card",
"tracking_id": "your_uniq_number",
"message": "Successfully processed",
"test": true,
"created_at": "2024-04-02T14:32:33.946Z",
"updated_at": "2024-04-02T14:32:35.000Z",
"paid_at": null,
"language": "en",
"redirect_url": "https://gateway.unonapay.com/process/e89abc1a-1d18-4d0f-83a1-7009b333dce0",
"status_code": null,
"id": "e89abc1a-1d18-4d0f-83a1-7009b333dce0",
"credit_card": {
"holder": "John Doe",
"stamp": "bb58cad9c1204ca2287b3e1006cc1a2c0fb8f062dde9e5232c8be5498bd0e62a",
"brand": "visa",
"last_4": "1097",
"first_1": "4",
"bin": "401200",
"bin_8": "40120000",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 7,
"exp_year": 2026,
"token_provider": null,
"token": "e3ba5977-8705-4496-bf90-a6a93d3d31cc"
},
"additional_data": {
"contract": [
"recurring"
]
},
"smart_routing_verification": {
"status": "successful"
},
"tokenization": {
"message": null,
"gateway_id": 3483,
"status": "successful"
},
"customer": {
"ip": null,
"email": null,
"device_id": null,
"birth_date": null
},
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"address": "1st Street",
"country": "US",
"city": "Denver",
"zip": "96002",
"state": "CO",
"phone": null
}
}
}