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
    }
  }
}