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:

Note

The request body must be wrapped in a top-level request{} object.

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 an array of up to 10 recent transactions 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.

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

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.

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.

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

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 `IN`, `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.
external_id	string (255) The customer's identifier in the merchant's system.

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":"2027"
      },
      "customer":{
         "ip":"127.0.0.1",
         "email":"john@example.com"
      }
   }
}

Response

In the transaction section response parameters replicate request parameters except the additional ones:

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.

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.

object

message required	string A tokenization result message.
status required	string A tokenization status. Possible values: `successful`, `failed`.

travel

object
An optional section with travel related data.

object
A section of detailed information about the payment.

receipt_text

array
A text that will be added to the customer email.

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": 2027,
      "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
    }
  }
}