Authorization
The authorization request is used either to check if there are enough funds available on the card to make a payment, or to hold the required amount for a future charge. The funds are not deducted from the cardholder's account but the available funds limit is shown as decreased by the authorization amount.
The authorization transaction should be followed by a capture request to charge the amount, or by a void request to cancel the hold.
Info
It is required to be PCI DSS validated to use this transaction type and send plain unencrypted card data.
Request
To initiate an authorization transaction, send a POST
request to https://processing.ecomcharge.com/transactions/authorizations
with the following parameters:
Parameter | Type | Description |
---|---|---|
amount * required |
bigInteger | An amount in minimal currency units, for example $32.45 must be sent as 3245 . |
currency * required |
string | A currency in the ISO-4217 format, for example, USD . |
description * required |
string(255) | A 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 by 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. |
expired_at | string | Time in the ISO-8601 format until which the transaction must be made: YYYY-MM-DDThh:mm:ssTZD, where YYYY – year (for example, 2024), 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 or –hh:mm indicating an offset from UTC). If the payment is not made by the specified date and time, expired status is assigned to the transaction. |
duplicate_check | boolean | The boolean parameter controls whether the payment gateway will do a duplicate check of the received requests to authorize a card. By default, it is true and duplicate requests with the same amount and number or token sent within 30 seconds after the original request will be rejected. |
dynamic_billing_descriptor | string | A dynamic billing descriptor. |
language | string | A language of the checkout page or the customer. If the parameter is set and transaction notification emails to customers are enabled, eComCharge will dispatch those emails in the 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 eComCharge 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 * conditionally required |
string(19) | The card number. The length is between 12 and 19 digits. Required, if a card token is not submitted in the request. |
verification_value * conditionally required |
string | 3- or 4-digit security code (called CVC2, CVV2 or CID depending on the credit card brand). It can be sent along with token parameter and in this case eComCharge will submit the card details with the given CVC2/CVV2/CID to the acquiring bank. 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 eComCharge system but can be required by the acquirer. |
exp_month * conditionally required |
string (2) | Card expiration month. Must be one or two digits (for example, 01). |
exp_year * conditionally required |
string (4) | Card expiration year. Must be 4 digits (for example, 2026). |
token * conditionally required |
string | A card token that was received in the transaction response when the card was charged for the first time. Required, if card details are not submitted in the request. |
skip_three_d_secure_verification | boolean | The parameter enables the option for the customer to skip the 3-D Secure verification check. If true , eComCharge doesn't launch the 3-D Secure verification to authorize the transactions. 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 , eComCharge forces the 3-D Secure verification to authorize the transactions. 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 for setting up the advanced scenario of payment processing with the 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. |
excluded_gateways | array | Array for working with cascading payments. |
masterpass | object | A section of Masterpass service. |
params | object | A section for Masterpass parameters. |
session | string | user session id. |
receipt_text | array | Text that will be added to the email for the client. Submit it as an array of strings, for example, ["First line", "Second line"] . |
contract * conditionally required |
array | An array which can contain the following elements:recurring - eComCharge 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 - eComCharge returns a card token to use it in the oneclick payment scheme. It means eComCharge will display a payment page with the prefilled card data and the customer will only be asked to enter CVC/CVV code and pass 3-D Secure verification to complete the payment.credit - eComCharge returns a card token to be used for a payoutcard_on_file - eComCharge returns a card token to be saved to the customer's profile and to be used in time-to-time charges initiated by the customer or by your application. See card_on_file section below to understand what cases the contract type covers. |
avs_cvc_verification | object | A section of AVS/CVC verification check. |
card_on_file | object | A section for parameters related to storing card details for future transactions. If not submitted, default values of initiator and type parameters are applied. |
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 with a saved card). |
type | string | Used only in case additional_data.card_on_file.initiator is merchant . delayed_charge - (default) prepaid expense charged to the customer's card increment - additional charge beyond the initially charged amount (for example, in the case of an upsell or in the case the product is exchanged for a more expensive one)resubmission - transaction resubmission after the previous charge has failed (for example, not sufficient funds on the card)reauthorization - repeat authorization (for example, when the merchant wants to reauthorize the previously authorized amount for future charges)no_show - a no-show charge (for example, no visit to a hotel). |
browser | object | Section of customer browser parameters. Used only for 3DS 2.0. |
accept_header | string | Value of Accept request HTTP header sent by the customer's browser. |
screen_width | integer | Screen width in pixels. Equals the screen.width parameter in JavaScript. |
screen_height | integer | Screen height in pixels. Equals the screen.height parameter in JavaScript. |
screen_color_depth | integer | Screen color depth in bits per pixel. Equals the screen.colorDepth parameter in JavaScript. Applicable values are:1 - 1 bit4 - 4 bits8 - 8 bits15 - 15 bits16 - 16 bits24 - 24 bits32 - 32 bits48 - 48 bits. |
window_width | integer | Browser window width in pixels. Equals the document.body.clientWidth parameter in JavaScript. |
window_height | integer | Browser window height in pixels. Equals the document.body.clientHeight parameter in JavaScript. |
language | string | Language of the navigator. Equals the navigator.language parameter in JavaScript. |
java_enabled | boolean | Indicates if the browser is Java-enabled or not. Equals the navigator.javaEnabled() parameter in JavaScript. |
user_agent | string | User agent string for the browser. Equals the navigator.userAgent parameter in JavaScript. |
time_zone | integer | Time zone difference, in minutes, from the current locale (host system settings) to UTC. Equals the new Date().getTimezoneOffset() parameter in JavaScript. |
time_zone_name | string | Time zone name. Equals the Intl.DateTimeFormat().resolvedOptions().timeZone parameter in JavaScript. |
customer * conditionally required |
object | A section of the customer information. Contact the 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 ISO 8601 format YYYY-MM-DD . |
taxpayer_id * conditionally required |
string | The customer's taxpayer ID. |
billing_address * conditionally required |
object | A section of the customer's address details. Contact the 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 (2) | 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 | 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 | A 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 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 authorization request
{
"request":{
"amount":100,
"currency":"USD",
"description":"Test transaction",
"tracking_id":"your_uniq_number",
"language":"en",
"test":true,
"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"
}
}
}
Example of the request with card token
{
"request":{
"amount":100,
"currency":"USD",
"description":"Test transaction",
"tracking_id":"your_uniq_number",
"test":true,
"billing_address":{
"first_name":"John",
"last_name":"Doe",
"country":"US",
"city":"Denver",
"state":"CO",
"zip":"96002",
"address":"1st Street"
},
"credit_card":{
"token":"40bd001563085fc35165329ea1ff5c5ecbdbbeef40bd001563085fc35165329e"
},
"customer":{
"ip":"127.0.0.1",
"email":"john@example.com"
}
}
}
Example of the request with information about ticket and tour voucher sales
{
"request":{
"amount":100,
"currency":"USD",
"description":"Test transaction",
"tracking_id":"your_uniq_number",
"test":true,
"billing_address":{
"first_name":"John",
"last_name":"Doe",
"country":"US",
"city":"Denver",
"state":"CO",
"zip":"96002",
"address":"1st Street"
},
"credit_card":{
"token":"40bd001563085fc35165329ea1ff5c5ecbdbbeef40bd001563085fc35165329e"
},
"customer":{
"ip":"127.0.0.1",
"email":"john@example.com"
},
"travel": {
"airline": {
"agency_code": "03",
"agency_name": "Corel travel",
"ticket_number": "390 5241 025377 1",
"booking_number": "DKZVUA",
"restricted_ticked_indicator": "0",
"legs": [
{
"airline_code": "B2",
"stop_over_code": "X",
"flight_number": "A3 971",
"departure_date_time": "2014-05-26T05:15:00",
"arrival_date_time": "2014-05-26T07:30:00",
"originating_country": "RU",
"originating_city": "Moscow",
"originating_airport_code": "DME",
"destination_country": "Greece",
"destination_city": "Athens",
"destination_airport_code": "ATH",
"coupon": "coupon code",
"class": "C"
}
],
"passengers":[
{
"first_name": "KONSTANTIN",
"last_name": "IVANOV"
},
{
"first_name": "JULIA",
"last_name": "IVANOVA"
}
]
}
}
}
}
Example of the request with additional receipt text
{
"request":{
"amount":100,
"currency":"USD",
"description":"Test transaction",
"tracking_id":"your_uniq_number",
"language":"en",
"test":true,
"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"
},
"additional_data":{
"receipt_text": ["First line", "Second Line"]
},
"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 * required |
object | |
uid * required |
string | A transaction UID. |
status * required |
string | A transaction status. |
message * required |
string | A processing result message. |
tracking_id * required |
string | A value of the tracking_id parameter submitted in the transaction request. |
language * required |
string | A value of the language parameter submitted in the 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 * required |
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 number. |
first_1 * required |
string | The first digit of the card number. |
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 | A card hash. It is constant even if either the expiration date or the cardholder is changed. |
token * required |
string | A card token. The token allows you to save the customer's details and run recurring payments or charge the customer whenever s/he makes a new purchase. |
token_provider * required |
string | The detected token provider. Possible values or null . |
receipt_url * required |
string | A transaction receipt URL. |
additional_data | object | A section of detailed information about the payment. |
masterpass | object | A section of Masterpass service. |
params | object | A section for Masterpass parameters. |
session | string | A user session ID. |
result | string | A section of the transaction result in Masterpass. |
status | string | A response status. Possible values: successful , failed . |
message | string | A message about a result of a Masterpass operation generated by eComCharge. |
error | string | A message about an error reason in Masterpass generated by eComCharge. Returned in case of an error. |
error_message | string | An error message generated by Masterpass. Returned in case there is an error. |
error_code | string | An error code generated by Masterpass. Returned in case there is an error. |
token | string | A Masterpass card token. Returned if the card is saved in Masterpass. |
receipt_text | array | Text that will be added to the customer email. |
redirect_url * required |
string | A URL of the page to finalize the transaction. If the status parameter is set to incomplete , redirect the customer to this URL. It runs the 3-D Secure verification of the cardholder. |
code * required |
string | Transaction processing code . |
friendly_message * required |
string | code description for the customer. |
authorization * required |
object | |
auth_code * required |
string | An authorization code provided by the acquirer. |
bank_code * required |
string | A transaction bank code. |
rrn * required |
string | A retrieval reference number, a transaction ID issued by the cards processing network. |
ref_id * required |
string | A transaction reference ID issued by the acquirer. |
message * required |
string | A message provided by the acquirer. |
billing_descriptor * required |
string | A billing descriptor assigned to the transaction. |
status * required |
string | A transaction status in the acquiring bank. |
avs_cvc_verification | object | An optional section with AVS/CVC verification results. |
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": "bf2ebe5b-0a31-4769-b61d-a46afa3b98fa",
"status": "successful",
"amount": 482,
"currency": "EUR",
"description": "Test transaction",
"type": "authorization",
"payment_method_type": "credit_card",
"tracking_id": "your_uniq_number",
"message": "Successfully processed",
"test": true,
"created_at": "2024-04-02T08:40:33.377Z",
"updated_at": "2024-04-02T08:40:38.455Z",
"paid_at": "2024-04-02T08:40:38.400Z",
"expired_at": null,
"recurring_type": "initial",
"closed_at": null,
"settled_at": null,
"manually_corrected_at": null,
"language": "en",
"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": "854d95e6-b7a5-41fb-b2a0-b8a6a0ae2021"
},
"receipt_url": "https://gateway.ecomcharge.com/customer/transactions/bf2ebe5b-0a31-4769-b61d-a46afa3b98fa/e6d23017fb43c6e2be34992efef50cfbadd3bb64942d7a9fe74a3e726a3907a6?language=en",
"status_code": null,
"gateway": {
"iframe": false
},
"mute_notifications": null,
"id": "bf2ebe5b-0a31-4769-b61d-a46afa3b98fa",
"additional_data": {
"contract": [
"recurring"
]
},
"redirect_url": "https://processing.ecomcharge.com/process/bf2ebe5b-0a31-4769-b61d-a46afa3b98fa",
"code": "S.0000",
"friendly_message": "The operation is successful.",
"smart_routing_verification": {
"status": "successful"
},
"authorization": {
"auth_code": "654321",
"bank_code": "05",
"rrn": "999",
"ref_id": "777888",
"message": "Authorization was approved",
"amount": 482,
"currency": "EUR",
"billing_descriptor": "test descriptor",
"gateway_id": 3208,
"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
}
}
}
Example of the response on incomplete 3-D Secure transaction
{
"transaction": {
"uid": "1f63b7ec-c58f-4a38-87bc-e8ea55a7d9c5",
"status": "incomplete",
"amount": 482,
"currency": "EUR",
"description": "Test transaction",
"type": "authorization",
"payment_method_type": "credit_card",
"tracking_id": "your_uniq_number",
"message": null,
"test": true,
"created_at": "2024-04-02T10:22:01.352Z",
"updated_at": "2024-04-02T10:22:03.058Z",
"paid_at": null,
"expired_at": null,
"recurring_type": "initial",
"closed_at": null,
"settled_at": null,
"manually_corrected_at": null,
"language": "en",
"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": "5d1392f2-864d-499b-b3ce-40e68d980d71"
},
"receipt_url": "https://gateway.ecomcharge.com/customer/transactions/1f63b7ec-c58f-4a38-87bc-e8ea55a7d9c5/4bfe945ab88e76507becb0f792f14426ad261afe2f809932cdcfd6c713ad6339?language=en",
"status_code": null,
"gateway": {
"iframe": true
},
"mute_notifications": null,
"id": "1f63b7ec-c58f-4a38-87bc-e8ea55a7d9c5",
"additional_data": {
"contract": [
"recurring"
]
},
"redirect_url": "https://processing.ecomcharge.com/process/1f63b7ec-c58f-4a38-87bc-e8ea55a7d9c5",
"code": "P.4012",
"friendly_message": "Redirect to pass 3-D Secure verification.",
"smart_routing_verification": {
"status": "successful"
},
"three_d_secure_verification": {
"status": "incomplete",
"message": "Authentication Available",
"ve_status": "Y",
"acs_url": null,
"pa_req": null,
"md": null,
"pa_res_url": "https://gateway.ecomcharge.com/process/1f63b7ec-c58f-4a38-87bc-e8ea55a7d9c5",
"eci": null,
"pa_status": null,
"xid": null,
"cavv": null,
"cavv_algorithm": null,
"fail_reason": null,
"method_process_url": null,
"creq": null
},
"authorization": {
"auth_code": null,
"bank_code": null,
"rrn": null,
"ref_id": null,
"message": null,
"amount": 482,
"currency": "EUR",
"billing_descriptor": null,
"gateway_id": 3483,
"status": "incomplete"
},
"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
}
}
}