Tokenization
The request is used to get a bank card token along with 3-D Secure verification details and then to use the token to submit either a payment or an authorization transaction.
Request
To get a card tokenized, send a POST
request to https://gateway.bepaid.by/transactions/tokenizations
with the following parameters:
Parameter | Type | Description |
---|---|---|
amount * required |
integer | 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 order short description. |
tracking_id. | string (255) | The ID of your transaction or order. Please, use unique values in order to get transaction information by query request otherwise you will get first transaction that we will find with tracking_id . |
duplicate_check | boolean | The parameter controls whether the payment gateway will do duplicate check of received requests to tokenize a card. By default, it is true and requests with the same amount and number within 30 seconds 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, bePaid will dispatch those emails in language locale. English is set by default. Possible values are: en - English es - Spanishtr - Turkishde - Germanit - Italianru - Russianzh - Chinesefr - Frenchda - Danishsv - Swedishno - Norwegianfi - Finnishpl - Polish ja - Japanesebe - Belarusianuk - Ukrainianka - Georgianro - Romanian |
notification_url | string | The URL where notification about a transaction will be posted to. The notification request format equals to a transaction response format. |
verification_url | string | The URL where transaction verification request will be posted to. The verification request format equals to a transaction response format. |
return_url * conditionally required |
string | URL on Merchant's side where bePaid will send Customer's browser when Customer returns from 3-D Secure verification. Required, if your merchant account is 3-D Secure enabled. |
test | boolean | The transaction will be a test one if it is true . |
credit_card | object | |
number * required |
string | The card number. The length is from 12 to 19 digits. |
verification_value * required |
string | 3- or 4-digit security code (called CVC2, CVV2 or CID depending on the credit card brand). |
holder * required |
string (32) | The cardholder name as it appears in the card. |
exp_month * required |
integer | The card expiration month expressed with two digits (for example, 01). |
exp_year * required |
integer | The card expiration year expressed with four digits (for example, 2007). |
three_d_secure | object | A section with the setting 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, false . |
additional_data | object | A section of detailed information about the payment. |
sub_brand | object | A section of detailed information about a credit card brand. |
brand | string | A subbrand name. Possible values are: halva . |
use_points | boolean | true - use loyalty points, false - not use loyalty points. The parameter is required for brand with value equal to halva . |
receipt_text | array | Text, that will be added to client's mail. Submit it as an array of strings, for example ["First line", "Second line"] . |
contract | array | An array, consisting of elements:recurring - bePaid 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 - bePaid returns a card token to use it in the one-click payment scheme. It means bePaid will open a payment page 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 - bePaid returns a card token to use it for a payout. |
customer * conditionally required |
object | A section of the customer information. Contact Tech Support Team to inquire if 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 billing address. Contact Tech Support Team to inquire 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 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 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 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 . |
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":"2020"
},
"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: visa , master , jcb , discover , dinersclub , amex , belkart and unionpay . |
product * required |
string | The card product: Electron , Classic , Gold , Standard , etc. |
sub_brand | string | The subbrand name. Possible values are: halva |
last_4 * required |
string | The last 4 digits of the card. |
first_1 * required |
string | The first digit of the card. |
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 allows you to 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. |
sub_brand | object | A section of detailed information about credit card brand. |
brand | string | The subbrand name. Possible values: halva . |
use_points | boolean | true - use loyalty points, false - not use loyalty points. The parameter is required for brand with value equal to halva . |
receipt_text | array | A text that will be added to the customer mail. |
Example of the response
{
"transaction":{
"customer":{
"ip":"127.0.0.1",
"email":"john@example.com"
},
"credit_card":{
"holder":"John Doe",
"stamp":"3709786942408b77017a3aac8390d46d77d181e34554df527a71919a856d0f28",
"token":"40bd001563085fc35165329ea1ff5c5ecbdbbeef40bd001563085fc35165329e",
"brand":"visa",
"product":"Gold",
"last_4":"0000",
"first_1":"4",
"exp_month":5,
"exp_year":2015
},
"additional_data":{
"receipt_text":["First line", "Second line"]
},
"billing_address":{
"first_name":"John",
"last_name":"Doe",
"address":"1st Street",
"country":"US",
"city":"Denver",
"zip":"96002",
"state":"CO",
"phone":null
},
"three_d_secure_verification":{
"eci":"6",
"pa_status":"Y",
"xid":null,
"cavv":null,
"cavv_algorithm":null,
"fail_reason":null,
"ve_status":"Y",
"message":"Authentication Successful",
"status":"successful"
},
"tokenization":{
"message":"The operation was successfully processed.",
"status":"successful"
},
"uid":"4107-310b0da80b",
"status":"successful",
"message":"Successfully processed",
"amount":100,
"currency":"USD",
"description":"Test order",
"type":"tokenization",
"tracking_id":"your_uniq_number",
"language":"en"
}
}