HTTP API

Welcome to ChargX payment gateway API documentation - set of clearly defined methods of communication between clients apps and payment gateway.

Before you start

Before you start, make sure:

You have access to your ChargX account and Publishable API Key. If not, follow the Getting Started guide

Headers

The only mandatory header required for all types of requests is x-publishable-api-key which should contain a value of Publishable API Key.

Retrieve pretransact keys

Before doing any payments you need to retrieve the pretransact keys:

Request:

GET https://api.chargx.io/pretransact

Headers:
x-publishable-api-key=pk_256c3fa9....t23f

Response:

{
  "authData": {
    "apiLoginID": "2R.....Vz",
    "clientKey": "743M................n6E3",
  },
  "isProduction": true,
  "cardTokenRequestUrl": "https://api.processor.net/xml/v1/request.api",
  "cardTokenRequestParams": {"securePaymentContainerRequest":{"merchantAuthentication":{"name":"2R.....Vz","clientKey":"743M................n6E3"},"data":{"type":"TOKEN","id":"37296fb7-0a75-5f25-77dc-0760091b89e6","token":{"cardNumber":"#cardNumber#","expirationDate":"#expirationDate#","cardCode":"#cardCode#"}}}},
  "googlePay": {
    "methodData": [
      {
        "supportedMethods": "https://google.com/pay",
        "data": {
          "environment": "PRODUCTION",
          "apiVersion": 2,
          "apiVersionMinor": 0,
          "merchantInfo": {
            "merchantId": "store_01KAty6123213231230732WR8",
            "merchantName": "Your Store Name"
          },
          "allowedPaymentMethods": [
            {
              "type": "CARD",
              "parameters": {
                "allowedAuthMethods": [
                  "PAN_ONLY",
                  "CRYPTOGRAM_3DS"
                ],
                "allowedCardNetworks": [
                  "MASTERCARD",
                  "VISA"
                ]
              },
              "tokenizationSpecification": {
                "type": "PAYMENT_GATEWAY",
                "parameters": {
                  "gateway": "authorizenet",
                  "gatewayMerchantId": "1723296"
                }
              }
            }
          ]
        }
      }
    ]
  },
  "applePay": {
    "paymentRequest": {
      "countryCode": "US",
      "currencyCode": "USD",
      "supportedNetworks": [
        "visa",
        "masterCard",
        "amex",
        "discover"
      ],
      "merchantCapabilities": [
        "supports3DS"
      ],
      "total": {
        "label": "Your Store Name",
        "amount": 0
      }
    }
  }
}

To exchange credit card details for a token, a tokenization system is used, which substitutes the actual credit card number with a unique, random string of characters called a token for secure online transactions

this should be a POST request to cardTokenRequestUrl endpoint and parameters taken from cardTokenRequestParams from Retrieve pretransact keys request.

you must replace stubs in cardTokenRequestParams, e.g. #cardNumber#, #expirationDate#, #cardCode# with real card details. The pseudo code looks like the following:

const cardTokenRequestParamsString = JSON.stringify(pretransactResponse.cardTokenRequestParams)
  .replace("#cardNumber#", testCard.cardNumber)
  .replace("#expirationDate#", testCard.expirationDate)
  .replace("#cardCode#", testCard.cardCode);
const cardTokenRequestParams = JSON.parse(cardTokenRequestParamsString);

Request:

POST https://api.processor.net/xml/v1/request.api

Headers:
content-type=application/json

Body:
{"securePaymentContainerRequest":{"merchantAuthentication":{"name":"2R.....Vz","clientKey":"743M................n6E3"},"data":{"type":"TOKEN","id":"37296fb7-0a75-5f25-77dc-0760091b89e6","token":{"cardNumber":"#cardNumber#","expirationDate":"#expirationDate#","cardCode":"#cardCode#"}}}},

Response:

Depending on underlying payment processor, the response coulde be one of the following:

{
    "opaqueData": {...},
}

{
    "token": "...",
}

Charge credit card

Use this method to authorize and capture a credit card payment.

Request:

POST https://api.chargx.io/transact

Headers:
x-publishable-api-key=pk_256c3fa9....t23f
content-type=application/json

Body:
{
  "currency":"USD",
  "amount":"22",
  "type":"fiat",
  "opaqueData":{...},
  "customer":{
    "name":"SamJohnatan",
    "email":"samj@email.com",
    "phone":"+18731944982"
  },
  "billingAddress":{
    "street":"6Street",
    "unit":"",
    "city":"Orlando",
    "state":"Florida",
    "zipCode":"31-566",
    "countryCode":"USA",
    "phone":"+18731944982"
  },
  "orderId":33,
}

Parameters

Field	Type	Required	Description
`amount`	`string`	✅ Yes	The amount to charge, represented as a string or numeric value.
`currency`	`string`	⚙️ Optional	The transaction currency. Format: ISO 4217. Default is USD.
`type`	`string`	✅ Yes	Defines the transaction type. Use `"fiat"` for standard currency payments.
`opaqueData`	`object`	✅ Yes	Encrypted or tokenized payment data (e.g. card details or digital wallet tokens).
`opaqueData.dataDescriptor`	`string`	Either dataDescriptor+dataValue or token	Encrypted or tokenized payment data
`opaqueData.dataValue`	`string`	Either dataDescriptor+dataValue or token	Encrypted or tokenized payment data
`opaqueData.token`	`string`	Either dataDescriptor+dataValue or token	Encrypted or tokenized payment data
`vaultId`	`string`	Either vaultId or opaqueData	An id of user vault
`cvv`	`string`	⚙️ Optional	The card security code. While this is not required, it is strongly recommended.
`customer`	`object`	⚙️ Optional	Customer details for the transaction.
`customer.name`	`string`	✅ Yes	Full name of the customer.
`customer.email`	`string`	✅ Yes	Customer email address for receipts or notifications.
`customer.phone`	`string`	⚙️ Optional	Customer phone number in international format.
`billingAddress`	`object`	⚙️ Optional	Billing address associated with the payment method.
`billingAddress.street`	`string`	✅ Yes	Street name and number.
`billingAddress.unit`	`string`	⚙️ Optional	Apartment, suite, or unit number.
`billingAddress.city`	`string`	✅ Yes	City of the billing address.
`billingAddress.state`	`string`	✅ Yes	State or province of the billing address.
`billingAddress.zipCode`	`string`	✅ Yes	ZIP or postal code.
`billingAddress.countryCode`	`string`	✅ Yes	3-letter ISO country code (e.g. `USA`).
`billingAddress.phone`	`string`	⚙️ Optional	Phone number associated with the billing address.
`orderId`	`string`	⚙️ Optional	Unique identifier for the related order or invoice from YOUR system

Response:

{
  "message":"Ok",
  "result":{
    "orderId":"order_01K74...WYKJ",
    "orderDisplayId": "79",
  }
}

Credit Card Transaction Declines

Credit card transactions can be declined for various reasons. To determine the cause of a decline, examine the /transact API response:

{
    "message": "Error creating transaction",
    "error": [
        {
            "errorCode": "44",
            "errorText": "This transaction has been declined."
        }
    ]
}

The platform may not provide specific reasons for a particular decline, but some details on declines are included in transaction responses, if available. There are some common decline reasons along with their associated Response Reason Codes:

Response Reason Code	Reason
2	The issuing bank declined the transaction.
3	Approval requires calling the issuing bank.
4	The card is reported lost or stolen and should be retained if possible.
27	Billing address does not match (AVS failure), declined based on configured rules.
44	Security code (CVV/CVC) failed verification.
45	Both AVS and security code failed validation, declined based on rules.
65	Security code mismatch, declined due to account rules.

Authorize credit card

Use this method to authorize a credit card payment. To actually charge the funds you will need to follow up with a capture transaction.

Request:

POST https://api.chargx.io/card/authorize

Headers:
x-publishable-api-key=pk_256c3fa9....t23f
content-type=application/json

Body:
{
  "currency":"USD",
  "amount":"22",
  "type":"fiat",
  "opaqueData":{...},
  "customer":{
    "name":"SamJohnatan",
    "email":"samj@email.com",
    "phone":"+18731944982"
  },
  "billingAddress":{
    "street":"6Street",
    "unit":"",
    "city":"Orlando",
    "state":"Florida",
    "zipCode":"31-566",
    "countryCode":"USA",
    "phone":"+18731944982"
  },
  "orderId":33,
}

Parameters

Field	Type	Required	Description
`amount`	`string`	✅ Yes	The amount to charge, represented as a string or numeric value.
`type`	`string`	✅ Yes	Defines the transaction type. Use `"fiat"` for standard currency payments.
`opaqueData`	`object`	✅ Yes	Encrypted or tokenized payment data (e.g. card details or digital wallet tokens).
`customer`	`object`	⚙️ Optional	Customer details for the transaction.
`customer.name`	`string`	✅ Yes	Full name of the customer.
`customer.email`	`string`	✅ Yes	Customer email address for receipts or notifications.
`customer.phone`	`string`	⚙️ Optional	Customer phone number in international format.
`billingAddress`	`object`	⚙️ Optional	Billing address associated with the payment method.
`billingAddress.street`	`string`	✅ Yes	Street name and number.
`billingAddress.unit`	`string`	⚙️ Optional	Apartment, suite, or unit number.
`billingAddress.city`	`string`	✅ Yes	City of the billing address.
`billingAddress.state`	`string`	✅ Yes	State or province of the billing address.
`billingAddress.zipCode`	`string`	✅ Yes	ZIP or postal code.
`billingAddress.countryCode`	`string`	✅ Yes	3-letter ISO country code (e.g. `USA`).
`billingAddress.phone`	`string`	⚙️ Optional	Phone number associated with the billing address.
`orderId`	`string`	⚙️ Optional	Unique identifier for the related order or invoice from YOUR system

Response:

{
  "message":"Ok",
  "result":{
    "orderId":"order_01K74...WYKJ",
    "orderDisplayId": "79",
  }
}

Capture a previously authorized amount

Use this method to capture funds reserved with a previous Authorize transaction request.

Request:

POST https://api.chargx.io/transaction/capture

Headers:
x-publishable-api-key=pk_256c3fa9....t23f
content-type=application/json

Body:
{
  "orderId":"order_01K74...WYKJ",
}

Parameters

Field	Type	Required	Description
`orderId`	`string`	✅ Yes	The order(transaction id) to capture

Response:

{
  "message":"Ok",
  "result":{
    "orderId":"order_01K74...WYKJ",
    "orderDisplayId": "79",
  }
}

Refund transaction

To refund a customer for a transaction that was successfully settled through the payment gateway.

Request:

POST https://api.chargx.io/transaction/refund

Headers:
x-publishable-api-key=pk_256c3fa9....t23f
content-type=application/json

Body:
{
  "orderId":"order_01K74...WYKJ",
}

Parameters

Field	Type	Required	Description
`orderId`	`string`	✅ Yes	The order(transaction id) to refund

Response:

{
  "message":"Ok",
}

Void transaction

To cancel an original transaction that is not yet settled. A Void prevents the transaction or the order from being sent for settlement.

Request:

POST https://api.chargx.io/transaction/void

Headers:
x-publishable-api-key=pk_256c3fa9....t23f
content-type=application/json

Body:
{
  "orderId":"order_01K74...WYKJ",
}

Parameters

Field	Type	Required	Description
`orderId`	`string`	✅ Yes	The order(transaction id) to void

Response:

{
  "message":"Ok",
}

Create subscription

Create subscription for recurring payments.

Request:

POST https://api.chargx.io/subscription

Headers:
x-publishable-api-key=pk_256c3fa9....t23f
content-type=application/json

Body:
{
  "variant_id": "premium-monthly-001",
  "opaqueData": {
    "dataDescriptor": "COMMON.ACCEPT.INAPP.PAYMENT",
    "dataValue": "947561b67cc948f38fd241ee1fb3f1e3"
  },
  "customer": {
    "email": "john.doe@example.com",
    "name": "John",
    "lastName": "Doe",
    "phone": "+15550001234"
  },
  "address": {
    "street": "123 Main Street",
    "city": "Los Angeles",
    "zipCode": "90001",
    "countryCode": "US",
    "unit": "Suite 204",
    "state": "CA"
  }
}

Parameters

Field	Type	Required	Description
`variant_id`	`string`	Yes	Identifier of the subscription product or plan variant.
`opaqueData.dataDescriptor`	`string`	Yes	Descriptor used to identify the payment tokenization method (e.g., `"COMMON.ACCEPT.INAPP.PAYMENT"`).
`opaqueData.dataValue`	`string`	Yes	Tokenized payment data value returned from the payment processor.
`customer.email`	`string (email)`	Yes	Customer email address.
`customer.name`	`string`	Yes	Customer first name.
`customer.lastName`	`string`	Yes	Customer last name.
`customer.phone`	`string`	No	Customer phone number.
`address.street`	`string`	Yes	Street address.
`address.city`	`string`	Yes	City of residence.
`address.zipCode`	`string`	Yes	ZIP or postal code.
`address.countryCode`	`string`	Yes	ISO country code.
`address.unit`	`string`	No	Apartment, suite, or unit number.
`address.state`	`string`	No	State or province (required based on region).

Response:

{
  "id":"subscription_947561b67cc948f38fd241ee1fb3f1e3",
}

Retrieve subscription

Retrieve subscription details of recurring payments.

Request:

GET https://api.chargx.io/subscription/<id>

Headers:
x-publishable-api-key=pk_256c3fa9....t23f
content-type=application/json

**Response:**

```bash
{
  "subscription": {
    "id": "subscription_01HYP3KJX473BY9ZPQH22F2Q8M",
    "name": "Premium Monthly Plan",
    "status": "active",
    "subscription_id": "sub_9f3a7320-cd45-4bbc-b762-b91671df15ad",
    "length": 1,
    "unit": "months",
    "start_date": "2025-02-01T12:00:00.000Z",
    "total_occurrences": 12,
    "trial_occurrences": 1,
    "amount": 19.99,
    "trial_amount": 0.00
  }
}

Delete subscription

Delete subscription of recurring payments.

Request:

DELETE https://api.chargx.io/subscription/<id>

Headers:
x-publishable-api-key=pk_256c3fa9....t23f
content-type=application/json

**Response:**

```bash
{
  "id":"subscription_947561b67cc948f38fd241ee1fb3f1e3",
  "object": "subscription",
  "canceled": true,
}

Create Vault

Store user tokenized credit/debit card into Vault for use in multi-time payments. Use Tokenize card request to tokenize card.

Request:

POST https://api.chargx.io/v1/vault

Headers:
x-publishable-api-key=pk_256c3fa9....t23f
content-type=application/json

Body:
{
  "opaqueData": { "token": "..." }
}

Parameters

Field	Type	Required	Description
`opaqueData`	`object`	✅ Yes	Encrypted or tokenized payment data (e.g. card details or digital wallet tokens).
`opaqueData.token`	`string`	✅ Yes	Encrypted or tokenized payment data

Response:

{
  "message":"Ok",
  "result":{
    "customerVaultId":13788232323,
  }
}

The vaultId can be used in Charge credit card request to charge the customer.

Delete Vault

Delete previously created Vault.

Request:

DELETE https://api.chargx.io/v1/vault?customerVaultId=13788232323

Headers:
x-publishable-api-key=pk_256c3fa9....t23f

Parameters

Field	Type	Required	Description
`customerVaultId`	`string`	✅ Yes	Existing Customer Vault identifier

Response:

{
  "message":"Ok",
}

Bank-to-bank

The following endpoints support bank-to-bank payments. Use them in sequence: create a link token → redirect the customer to connect their bank → exchange the public token → create a transaction.

Create link token

Creates a link_token used to initialize the bank connection flow. Your frontend uses this token with UI lib so the customer can connect their bank account. At least one of custPhoneNumber or custEmail is required.

Request:

POST https://api.chargx.io/v1/bank-to-bank/create_link_token

Headers:
x-publishable-api-key=pk_256c3fa9....t23f
content-type=application/json

Body:
{
  "clientName": "Your App Name",
  "redirectUri": "https://yourapp.com/callback",
  "custEmail": "customer@example.com",
  "custPhoneNumber": "+15551234567",
  "custFirstName": "Jane",
  "custLastName": "Doe",
  "themeColor": "0066CC",
  "themeLogo": "https://yourapp.com/logo.png"
}

Parameters

Field	Type	Required	Description
`clientName`	`string`	✅ Yes	Your application or merchant name shown in the bank connection flow.
`redirectUri`	`string`	✅ Yes	URL where the customer is redirected after completing or abandoning the bank connection. Must be a valid URL.
`custPhoneNumber`	`string`	⚙️ Conditional	Customer phone number. At least one of `custPhoneNumber` or `custEmail` is required.
`custEmail`	`string`	⚙️ Conditional	Customer email address. At least one of `custPhoneNumber` or `custEmail` is required.
`custFirstName`	`string`	⚙️ Optional	Customer first name.
`custLastName`	`string`	⚙️ Optional	Customer last name.
`themeColor`	`string`	⚙️ Optional	6-character HEX color code (e.g. `0066CC`) for Link UI theming.
`themeLogo`	`string`	⚙️ Optional	URL of your logo for the Link UI.

Response:

{
  "message": "Ok",
  "link_token": "link-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Error response (e.g. validation failure):

{
  "message": "Failed to create link token",
  "error": "Failed to create link token"
}

Exchange public token

After the customer completes the bank connection, it redirects to your redirectUri with a public_token. Exchange that token for a bankToken and optional account details. Use bankToken when calling the transact endpoint.

Request:

POST https://api.chargx.io/v1/bank-to-bank/public_token_exchange

Headers:
x-publishable-api-key=pk_256c3fa9....t23f
content-type=application/json

Body:
{
  "publicToken": "public-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Parameters

Field	Type	Required	Description
`publicToken`	`string`	✅ Yes	The public token returned after the customer completes the bank connection (e.g. from your redirect URI query params).

Response:

{
  "message": "Ok",
  "bankToken": "btok_xxxxxxxxxxxxxxxx",
  "bankName": "Chase",
  "bankAccountLastFour": "1234"
}

Error response:

{
  "message": "Failed to exchange public token",
  "error": "Failed to exchange public token"
}

Bank-to-bank transact

Creates a bank-to-bank transaction using a bankToken obtained from Exchange public token. A store-level discount (5%) is applied to the amount before charging. Optionally pass linkToken from Create link token to associate the payment with a cached customer.

Request:

POST https://api.chargx.io/v1/bank-to-bank/transact

Headers:
x-publishable-api-key=pk_256c3fa9....t23f
content-type=application/json

Body:
{
  "bankToken": "btok_xxxxxxxxxxxxxxxx",
  "amount": 99.99,
  "orderId": "order-123-from-your-system",
  "linkToken": "link-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Parameters

Field	Type	Required	Description
`bankToken`	`string`	✅ Yes	Bank token from the Exchange public token response.
`amount`	`number`	✅ Yes	Transaction amount (e.g. in store’s default currency). A store-defined discount may be applied before charging.
`orderId`	`string`	✅ Yes	Unique identifier for this order from your system (e.g. your order or invoice id).
`linkToken`	`string`	⚙️ Optional	Link token from Create link token. Used to look up the cached customer.

Response:

{
  "message": "Ok",
  "result": {
    "orderId": "order_01K74...WYKJ",
    "orderDisplayId": "79",
    "transactionId": "..."
  }
}

Error response:

{
  "message": "Error creating bank-to-bank transaction: <error detail>",
  "error": "<error detail>"
}

HTTP API

Before you start

REST API endpoint

Headers

Retrieve pretransact keys

Tokenize card

Charge credit card

Authorize credit card

Capture a previously authorized amount

Refund transaction

Void transaction

Create subscription

Retrieve subscription

Delete subscription

Create Vault

Delete Vault

Bank-to-bank

Create link token

Exchange public token

Bank-to-bank transact

On this page