Payment

Payment transaction is a combination of authorization and capture processed at a time. This transaction type is generally used when the goods or services can be immediately provided to the customer.

Info

It is required to be PCI DSS validated to use the operation and send a plain unencrypted card data.

Request

To initiate a payment transaction, send a POST request to https://processing.ecomcharge.com/transactions/payments 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`.
expired_at	string	Date and time till a transaction can be done. 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).
duplicate_check	boolean	The boolean parameter controls whether the payment gateway will do duplicate check of received requests to charge a card. By default, it is `true` and requests with the same `amount` and `number` or `token` within 30 seconds will be rejected.
dynamic_billing_descriptor	string	A dynamic billing descriptor.
language	string	Language of your checkout page or customer. If the parameter is set and transaction notification emails to customers are enabled, eComCharge will dispatch those emails in `language` locale. English (`en`) is set by default. Possible values of `language` parameter.
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 eComCharge will send the 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 (19)	Card number.
verification_value * 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 to acquiring bank card details with the given CVC2/CVV2/CID.
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).
token * conditionally required	string	Instead of the above 5 parameters you can send the card token you've saved from the transaction response when the card was charged for the first time. If a card token is used, then the `additional_data.contract` parameter must be specified.
skip_three_d_secure_verification	boolean	The parameter is used when you want your customer skip the 3-D Secure verification. Contact the tech support team to check if you can apply this parameter. If `true`, eComCharge doesn't launch the 3-D Secure verification for payment transactions when a card token is submitted. Set to `false`, by default. The `force_three_d_secure_verification` parameter overrides the `skip_three_d_secure_verification` parameter, if both are set to `true`.
force_three_d_secure_verification	boolean	The parameter is used when you want your customer obligatory take the 3-D Secure check. Contact the tech support team to check if you can apply this parameter. If `true`, eComCharge forces the 3-D Secure verification for payment transactions when a card token is submitted. Set to `false`, by default. The `force_three_d_secure_verification` parameter overrides the `skip_three_d_secure_verification` parameter, if both are set to `true`.
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 `true` to apply the advanced scenario. Otherwise, set to `false`.
additional_data	object	A section with additional transaction data.
p2p	object	A parameter section for AFT transactions.
service_id * conditionally required	string	The parameter is required for an AFT transaction. Request the parameter value from your manager.
service_extension * conditionally required	string	The parameter is required for an AFT transaction. Request the parameter value from your manager.
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	A 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` - eComCharge 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` - eComCharge returns a card token to use it in the one-click payment scheme. It means eComCharge 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` - eComCharge returns a card token to use it for a payout `card_on_file` - eComCharge returns a card token to save it to a customer profile and to use the token in time-to-time charges initiated by a customer or by your application. See `card_on_file` section below to understand what cases the contract type covers. `card_on_file` option in the `Payment` operation works not with all acquirers. If you want to use the `card_on_file` option, please contact your account manager.
avs_cvc_verification	object	A section of AVS/CVC verification check.
card_on_file	string	It sets flags submitted to a payment network why and what you charged a previously saved card for. If no 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 and 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 card `increment` - 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)
browser	object	Parameters from section are used only for 3DS 2.0.
accept_header	integer	Value of `Accept` request HTTP header sent by the cardholder browser.
screen_width	integer	Screen width in pixels. Equals the `screen.width` parameter of JavaScript.
screen_height	integer	Screen height in pixels. Equals the `screen.height` parameter of JavaScript.
screen_color_depth	integer	Screen color depth in bits per pixel. Equals the `screen.colorDepth` parameter of JavaScript. Applicable values are: `1` - 1 bit `4` - 4 bits `8` - 8 bits `15` - 15 bits `16` - 16 bits `24` - 24 bits `32` - 32 bits `48` - 48 bits.
window_width	integer	Browser window width in pixels. Equals the `document.body.clientWidth` parameter of JavaScript.
window_height	integer	Browser window height in pixels. Equals the `document.body.clientHeight` parameter of JavaScript.
language	string	Language of the navigator. Equals the `navigator.language` parameter of JavaScript.
java_enabled	boolean	Indicates if the browser is Java-enabled or not. Equals the `navigator.javaEnabled()` parameter of JavaScript.
user_agent	string	User agent string for the browser. Equals the `navigator.userAgent` parameter of JavaScript.
time_zone	integer	Time zone difference, in minutes, from the current locale (host system settings) to UTC. Equals the `new Date().getTimezoneOffset()` parameter of JavaScript.
time_zone_name	string	Time zone name. Equals the `Intl.DateTimeFormat().resolvedOptions().timeZone` parameter of JavaScript.
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`.
taxpayer_id * conditionally required	string	The customer's taxpayer ID. Contact the Tech Support Team to check if you should submit this parameter.
billing_address	object	A section of parameters related to 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. Max length: 30 chars.
last_name * conditionally required	string (30)	The customer's last name. Max length: 30 chars.
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	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	A section of 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 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",
      "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":"2020"
      },
      "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 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":"2020"
      },
      "additional_data":{
        "receipt_text": ["First line", "Second Line"]
      },
      "customer":{
        "ip":"127.0.0.1",
        "email":"john@example.com"
      }
  }
}

Example of the request example with information about ticket and tour voucher sale

{
  "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"
          }
        ]
      }
    }
  }
}

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.
type * required	string	A transaction type.
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.
payment_method_type * required	string	Payment method used to complete the transaction. Possible vaalues: `credit_card`.
credit_card	object
brand * required	string	Detected card brand: `visa`, `master`, `jcb`, `discover`, `dinersclub`, `amex`, `belkart` and `unionpay`.
product * required	string	Card product: `Electron`, `Classic`, `Gold`, `Standard`, etc.
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 expiration dates or cardholder are 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.
token_provider * required	string	A detected token provider. Possible values: `apple_pay`.
receipt_url * required	string	A transaction receipt URL.
additional_data	object	A section of detailed information about the payment.
masterpass	object	A Masterpass service section.
params	object	A section for Masterpass parameters.
session	string	A user session ID.
result	object	A section for the result of an operation in Masterpass.
status	string	A response status. Possible values: `successful`, `failed`.
message	string	A message about Masterpass operation result 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 of an error.
error_code	string	An error code generated by Masterpass. Returned in case of an error.
token	string	A Masterpass card token. Returned in case of saving the card.
receipt_text	array	Text that will be added to the email sent to the customer.
payment	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 cards processing network.
ref_id * required	string	An transaction reference ID provided by the acquirer.
message * required	string	A processing result message provided by the acquirer.
billing_descriptor * required	string	A billing descriptor assigned to the transaction.
status * required	string	A status of the processed transaction in the acquiring bank.
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.
be_protected_verification	object	A section of parameters of the beProtected verification service.
avs_cvc_verification	object	An optional section with AVS/CVC verification results.

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,
        "token_provider":"apple_pay"// if txn was processed via Apple Pay or null if not
      },
      "receipt_url": "https://gateway.ecomcharge.com/customer/transactions/4107-310b0da80b/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
      "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
      },
      "payment":{
        "auth_code":"654321",
        "bank_code":"00",
        "rrn":"999",
        "ref_id":"777888",
        "message":"The operation was successfully processed.",
        "gateway_id":317,
        "billing_descriptor":"TEST GATEWAY BILLING DESCRIPTOR",
        "status":"successful"
      },
      "uid":"4107-310b0da80b",
      "status":"successful",
      "message":"Successfully processed",
      "amount":100,
      "currency":"USD",
      "description":"Test order",
      "type":"payment",
      "tracking_id":"your_uniq_number",
      "language":"en",
      "payment_method_type":"credit_card"
  }
}

Example of the response on incomplete 3-D Secure transaction

{
    "transaction": {
        "amount": 100,
        "billing_address": {
            "address": "1st Street",
            "city": "Riga",
            "country": "LV",
            "first_name": "John",
            "last_name": "Doe",
            "phone": null,
            "state": null,
            "zip": "96002"
        },
        "created_at": "2015-05-12T15:32:43+03:00",
        "credit_card": {
            "brand": "visa",
            "product":"Gold",
            "exp_month": 6,
            "exp_year": 2016,
            "first_1": "4",
            "holder": "TESTING CARD",
            "last_4": "1112",
            "stamp": "6d9e060e3c91db74d0a0ba791cb78dd2de30f47944709841749eb15da66d05e4",
            "token": "12fc4d054e8242f1a1457dfe88bdfb32c5fd605e7660d59116dff00a91e3297b"
        },
        "receipt_url": "https://gateway.ecomcharge.com/customer/transactions/1-68bf762e1f/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
        "currency": "USD",
        "customer": {
            "device_id": "12312312321fff67",
            "email": "john@example.com",
            "ip": "127.0.0.1"
        },
        "description": "Test transaction",
        "id": "1-68bf762e1f",
        "language": "en",
        "message": null,
        "redirect_url": "https://processing.ecomcharge.com/process/1-68bf762e1f",
        "status": "incomplete",
        "test": null,
        "tracking_id": "tracking_id_000",
        "payment_method_type":"credit_card",
        "type": "payment",
        "uid": "1-68bf762e1f",
        "updated_at": "2015-05-12T15:32:49+03:00"
    }
}

Example of the response with failed beProtected section

{
  "transaction":{
    "customer":{
      "ip":"127.0.0.1",
        "email":"john@example.com"
    },
    "credit_card":{
      "holder":"Johnathan Doe",
      "stamp":"a825df7faba8804619aef7a6d5a5821ec292fce04e3e43933ca33d0692df90b4",
      "brand":"visa",
      "product":"Gold",
      "last_4":"0000",
      "first_1":"4",
      "token":"2bbd9fb7307dace37a9c2db1b4cca6f0c0dd143eac17294daab769224bff6ae2",
      "exp_month":1,
      "exp_year":2020
    },
    "receipt_url": "https://gateway.ecomcharge.com/customer/transactions/1-2d4b20c72a/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    "billing_address":{
      "first_name":"John",
      "last_name":"Doe",
      "address":"1st Street",
      "country":"US",
      "city":"Denver",
      "zip":"96002",
      "state":"CO",
      "phone":null
    },
    "be_protected_verification":{
      "status":"failed",
      "message":"Transaction didn't pass risk management system.",
      "limit":{
        "volume":false,
        "count":false,
        "max":true,
        "current_volume":100,
        "current_count":1
      },
      "white_black_list":{
        "card_number":"black",
        "ip":"absent",
        "email":"absent"
      },
      "rules":{
        "1_123_My Shop":{
          "more_100_eur" : {"Transaction amount more than 100 AND Transaction currency is EUR": "passed"}
        },
        "1_John Doe":{},
        "eComCharge":{}
      }
    },
    "uid":"1-2d4b20c72a",
    "status":"failed",
    "amount":100,
    "currency":"USD",
    "description":"Test transaction",
    "type":"payment",
    "tracking_id":"tracking_id_000",
    "payment_method_type":"credit_card",
    "message":"Merchant terminal limits exceeded (maximum transaction amount). Transaction didn't pass anti-fraud checks.",
    "test":true,
    "created_at":"2014-06-11T12:05:54+03:00",
    "updated_at":"2014-06-11T12:05:54+03:00",
    "id":"1-2d4b20c72a"
  }
}

Example of the response with successful beProtected section

{
  "transaction":{
    "customer":{
      "ip":"127.0.0.1",
      "email":"john@example.com"
    },
    "credit_card":{
      "holder":"Johnathan Doe",
      "stamp":"a825df7faba8804619aef7a6d5a5821ec292fce04e3e43933ca33d0692df90b4",
      "brand":"visa",
      "product":"Gold",
      "last_4":"0000",
      "first_1":"4",
      "token":"2bbd9fb7307dace37a9c2db1b4cca6f0c0dd143eac17294daab769224bff6ae2",
      "exp_month":1,
      "exp_year":2020
    },
    "receipt_url": "https://gateway.ecomcharge.com/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    "billing_address":{
      "first_name":"John",
      "last_name":"Doe",
      "address":"1st Street",
      "country":"US",
      "city":"Denver",
      "zip":"96002",
      "state":"CO",
      "phone":null
    },
    "be_protected_verification":{
      "status":"successful",
      "limit":{
        "volume":false,
        "count":false,
        "max":false,
        "current_volume":90,
        "current_count":1
      },
      "white_black_list":{
        "card_number":"absent",
        "ip":"absent",
        "email":"absent"
      },
      "rules":{
        "1_123_My Shop":{
          "more_100_eur" : {"Transaction amount more than 100 AND Transaction currency is EUR": "passed"}
        },
        "1_John Doe":{},
        "eComCharge":{}
      }
    },
    "payment":{
      "auth_code":"654321",
      "bank_code":"00",
      "rrn":"999",
      "ref_id":"777888",
      "message":"Payment was approved",
      "gateway_id":85,
      "billing_descriptor":"TEST GATEWAY BILLING DESCRIPTOR",
      "status":"successful"
    },
    "uid":"2-52671c8733",
    "status":"successful",
    "amount":90,
    "currency":"USD",
    "description":"Test transaction",
    "type":"payment",
    "tracking_id":"tracking_id_000",
    "payment_method_type":"credit_card",
    "message":"Successfully processed",
    "test":true,
    "created_at":"2014-06-11T12:04:59+03:00",
    "updated_at":"2014-06-11T12:04:59+03:00",
    "avs_cvc_verification": {
      "cvc_verification" : {
        "result_code": "M"
      },
      "avs_verification" : {
        "result_code": "M"
      }
    }
  }
}