Skip to content

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 this transaction and send 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:

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 by 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.
expired_at
string
Time in the ISO-8601 format until which the transaction payment must be made: YYYY-MM-DDThh:mm:ssTZD, where YYYY – year (for example, 2023), 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 charge 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
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 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.
object
number
required
string (19)
Card number.
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
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).
token
conditionally required
string
Instead of the 5 parameters above 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 enables the option for the customer to skip the 3-D Secure verification check. 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. By default, false.
The force_three_d_secure_verification parameter overrides the skip_three_d_secure_verification parameter, if both are set to true.
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. 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. By default, false.
The force_three_d_secure_verification parameter overrides the skip_three_d_secure_verification parameter, if both are set to true.
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.
travel
object
An optional section with travel related data.
conditionally required
object
A section of the customer information.
Contact the Tech Support Team to check 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 need to submit this parameter.
external_id
string (255)
The customer's identifier in the merchant's system.
conditionally required
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. Max length: 30 chars.
last_name
conditionally required
string (30)
The customer's last name. Max length: 30 chars.
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 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.
object
A section with additional transaction data.
expected_bank_code
string
If this field contains a processing error, it will be sent as the value of the code parameter in the response. The parameters message and friendly_message will have the values corresponding to the specified error code. This logic applies only to test transactions.
conditionally required
object
Section with the payment recipient information.
first_name
conditionally required
string
The first name of the payment recipient.
last_name
conditionally required
string
The last name of the payment recipient.
account_number
conditionally required
string
The identifier of the payment recipient's account.
account_number_type
conditionally required
string
The format of the payment recipient's account identifier. Possible values: card, iban, bic, other.
conditionally required
object
Address information of the payment recipient.
address_line1
conditionally required
string
Street address of the payment recipient.
zip
conditionally required
string
Postal code of the payment recipient's address.
city
conditionally required
string
City of the payment recipient.
country
conditionally required
string
Country of the payment recipient in ISO 3166-1 Alpha-2 format.
object
A 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.
object
A section of Masterpass service.
object
A section for Masterpass parameters.
session
string
user session id
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 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 payout

card_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. card_on_file option in the payment transaction doesn't work 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.
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).
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 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 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.
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":"2027"
      },
      "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":"2027"
      },
      "additional_data":{
        "receipt_text": ["First line", "Second Line"]
      },
      "customer":{
        "ip":"127.0.0.1",
        "email":"john@example.com"
      }
  }
}
Example of the request 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_ticket_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:

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 corresponding to the processing code (code).
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 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 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 lets you save the customer's details and charge them whenever they make new purchases, or you renew their services.
token_provider
required
string
The detected token provider.

Possible values or null.
receipt_url
required
string
A transaction receipt URL.
object
A section of detailed information about the payment.
masterpass
object
A Masterpass service section.
receipt_text
array
Text that will be added to the email sent to the customer.
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 card processing service.
ref_id
required
string
A 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.
code
required
string
Transaction processing code .
friendly_message
required
string
code description for the customer.
avs_cvc_verification
object
An optional section with AVS/CVC verification results.
object
A section of parameters of Smart Routing verification results.
status
string
Smart Routing check status for the transaction.

Masterpass section

object
A Masterpass service section.
object
A section for the result of a transaction 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 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 in case the card is saved.
object
session
string
A user session ID.
Example of the response
{
  "transaction": {
    "uid": "12803315-c061-4f8d-8f42-4abaf3f8319d",
    "status": "successful",
    "amount": 492,
    "currency": "EUR",
    "description": "Test transaction",
    "type": "payment",
    "payment_method_type": "credit_card",
    "tracking_id": "your_uniq_number",
    "message": "Successfully processed",
    "test": true,
    "created_at": "2024-04-02T12:47:26.818Z",
    "updated_at": "2024-04-02T12:47:30.960Z",
    "paid_at": "2024-04-02T12:47:30.909Z",
    "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": 2027,
      "token_provider": null,
      "token": "10f43f34-5a34-430a-afd7-affe77ed5c90"
    },
    "receipt_url": "https://gateway.ecomcharge.com/customer/transactions/12803315-c061-4f8d-8f42-4abaf3f8319d/6392098201d357893deef7eb11270e863da7004ebfcd27bdb3235280e90ebf99?language=en",
    "status_code": null,
    "gateway": {
      "iframe": true
    },
    "mute_notifications": null,
    "id": "12803315-c061-4f8d-8f42-4abaf3f8319d",
    "additional_data": {
      "contract": [
        "recurring"
      ]
    },
    "redirect_url": "https://processing.ecomcharge.com/process/12803315-c061-4f8d-8f42-4abaf3f8319d",
    "code": "S.0000",
    "friendly_message": "The operation is successful.",
    "smart_routing_verification": {
      "status": "successful"
    },
    "payment": {
      "auth_code": "654321",
      "bank_code": "05",
      "rrn": "999",
      "ref_id": "777888",
      "message": "Payment was approved",
      "amount": 492,
      "currency": "EUR",
      "billing_descriptor": "test descriptor",
      "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
    }
  }
}
Example of the response with incomplete 3-D Secure verification
{
  "transaction": {
    "uid": "c37c2df6-707e-4e49-bc0f-1c0a1800a238",
    "status": "incomplete",
    "amount": 492,
    "currency": "EUR",
    "description": "Test transaction",
    "type": "payment",
    "payment_method_type": "credit_card",
    "tracking_id": "your_uniq_number",
    "message": null,
    "test": true,
    "created_at": "2024-04-02T13:44:22.590Z",
    "updated_at": "2024-04-02T13:44:24.802Z",
    "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": 2027,
      "token_provider": null,
      "token": "34577a72-ed65-4b0c-85a1-f62262f54af6"
    },
    "receipt_url": "https://gateway.ecomcharge.com/customer/transactions/c37c2df6-707e-4e49-bc0f-1c0a1800a238/571fddcc764f75f0daad3acb746d46a80c4112e51d43eda8538aa1b27597120e?language=en",
    "status_code": null,
    "gateway": {
      "iframe": true
    },
    "mute_notifications": null,
    "id": "c37c2df6-707e-4e49-bc0f-1c0a1800a238",
    "additional_data": {
      "contract": [
        "recurring"
      ]
    },
    "redirect_url": "https://processing.ecomcharge.com/process/c37c2df6-707e-4e49-bc0f-1c0a1800a238",
    "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://processing.ecomcharge.com/process/c37c2df6-707e-4e49-bc0f-1c0a1800a238",
      "eci": null,
      "pa_status": null,
      "xid": null,
      "cavv": null,
      "cavv_algorithm": null,
      "fail_reason": null,
      "method_process_url": null,
      "creq": null
    },
    "payment": {
      "auth_code": null,
      "bank_code": null,
      "rrn": null,
      "ref_id": null,
      "message": null,
      "amount": 492,
      "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
    }
  }
}