API Endpoint Overview

This section contains all the important information needed to communicate with the API.

🚧

Note

We use the Basic Authentication method in all our request samples as it simplifies testing and helps you quickly become familiar with the PayConex™ V4 API. Keep in mind that this option is only available in the certification environment.

Environment URLs

There are two different environments for this service: the testing/certification environment is for testing integrations, and production is for live production requests.

These environment URLs are suffixed by /api/v4/. This stands for the latest V4 version of the PayConex™ API. For example, this is the full URL for making a simple sale transaction in the certification environment:

https://api-cert.payconex.net/api/v4/accounts/{accountId}/payments/sale

We use the following format of the URL path, HTTP method, and the body that is specific to making the request throughout the documentation.

For example,

POST /api/v4/accounts/{accountId}/payments/sale

{
  "bfTokenReference": "PAYCONEX_TOKEN",
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "5",
    "currency": "USD"
  }   
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:sale

🚧

Keep in mind

This implies that at least one of these scopes is required of your API key(s).

As API keys are crucial in forming the authorization headers, it is also important to specify the scopes required to make certain HTTP requests, such as payments, iframe configuration, webhook triggers and account updater subscriptions.

For more, see API Key Management

Header Configuration

The essential headers consist of the following:

For example,

{
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Basic Base64(id:secret)"
  }
}

Empty Strings as Body Parameters

In addition to Data Projection, the V4 API allows empty strings even if a certain nested field is required in the body (shippingAddress.address1 for example). Behind the scenes, these are treated as the null value.

This is especially useful if your integration uses statically-typed languages such as Golang, C++, C#, or Java - and in cases where a field is not required in the form and, by default, is passed on as the empty string "" (a good use case is when the merchant builds their own form for their POS systems such as stores, shops, or similar).

Request

POST /api/v4/accounts/{accountId}/payments/sale

For example, the following shippingAddress is entirely stripped out in this case, meaning that the V4 API additionally flattens out the request object on all levels if necessary.

{
  "shippingAddress": {
    "address1": "",
    "address2": "",
    "city": "",
    "state": "",
    "zip": "",
    "country": "",
    "company": "",
    "recipient": "",
    "recipientPhone":""
  },
  "bfTokenReference": "PAYCONEX_TOKEN",
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "5",
    "currency": "USD"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:sale

Response and Transaction Metadata

{
  "transactionId": "000000064566",
  "status": "CAPTURED",
  "timestamp": "2025-08-18T16:42:21.000000Z",
  "customer": {
    "name": "Alice"
  },
  "trace": {
    "history": [
      {
        "action": "transaction",
        "requestId": "b11285f5-4dbf-4930-98a4-0e223f2aec74",
        "correlationId": "5e912e79-95fe-48b2-992c-6c3a20460deb",
        "timestamp": "2025-08-18T11:42:19-05:00"
      }
    ],
    "networkTransactionId": "015230416096542CN  "
  },
  "amounts": {
    "currency": "USD",
    "approved": "4.00",
    "requested": "4.00",
    "balance": "4.00"
  },
  "auth": {
    "code": "OK1260",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA"
  },
  "card": {
    "name": "Alice",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "4.00"
  }
}

API Header Response Codes

These are some general header response codes for all the V4 API endpoints.

Example Error Response

{
  "message": "Unauthenticated",
  "errorCode": 40002,
  "errorType": "authentication",
  "source": "Headers",
  "value": "Authorization",
  "traceId": "a3d5dbb0-e404-435f-b450-a0b3bc8db465",
  "details": []
}

🚧

TraceId

The traceId is primarily used by the Bluefin Technical Support to identity the issue if there is an internal error that's not clear enough to the merchant or similar.

The traceId and requestId are interchangeable. The only difference is that requestId is provided in the response headers whereas traceId in the response body. These are saved as transaction metadata in an action of the transaction history.

Correlation Identifier

Compared to the trace/request identifier generated and used internally by the Bluefin Services, the correlation ID is user-defined and is typically used within merchant systems.

🚧

Not Required

If no correlation ID is specified, we generate unique one on each request by default. This is performed separately from the request ID.

While the correlation ID can be unique at the start of a a process (if specified), the request ID is consistently unique per request/response.

Request Example

The correlation ID defined in the request headers is echoed back out in the response headers along with the request ID.

For example,

curl -v --request POST \
  --url https://api-cert.payconex.net/api/v4/accounts/<accountId>/payments/sale \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <REDACTED>' \
  --header 'correlation-id: 7bc98b7f-5f3c-4276-ab92-3efee124bc51' \
  --data '{
  "transactionId": "000000064326",
  "amounts": {
    "total": "4",
    "currency": "USD"
  },
  "posProfile": "ECOMMERCE",
  "bfTokenReference": "bft_77a..."
}'

Response Headers

< HTTP/2 200 
< cache-control: no-cache, private
< content-type: application/json
< correlation-id: 7bc98b7f-5f3c-4276-ab92-3efee124bc51
< request-id: b696eb1a-81ff-483f-8432-11e5db251370

On successful response, the correlation ID is saved as transaction metadata in the transaction history.

📘

Note

In the following example, the same correlation ID is used for transaction initialization, allowing the merchant to track the entire transaction processing cycle per their unique identifier (generated at the start of the process).

The merchant may as well specify a unique ID per request/action considering that suits the implementation logic within their systems.

  "trace": {
    "history": [
      {
        "action": "init",
        "requestId": "e11a91d4-6d9a-4af5-8e4d-692a26b85b19",
        "correlationId": "7bc98b7f-5f3c-4276-ab92-3efee124bc51",
        "timestamp": "2025-08-15T06:23:53-05:00"
      },
      {
        "action": "transaction",
        "requestId": "b696eb1a-81ff-483f-8432-11e5db251370",
        "correlationId": "7bc98b7f-5f3c-4276-ab92-3efee124bc51",
        "timestamp": "2025-08-15T06:24:11-05:00"
      }
    ],
    "networkTransactionId": "015227539789449G939"
  },

The merchant can assign different correlation IDs depending on the process, using them to identify specific operations, such as:

• API Key Management
• Creating Iframe configuration and instance
• Checkout Component Integration
• Processing Transactions
• Transaction Management

For example, there could be a logic where the merchant prefixes the correction IDs with the corresponding operation, constructing their custom identifier.

"auth-6a6ee02f-77cc-4989-9a6f-6b3d09d32575" # authorization transaction
"capt-0f18b7f7-4909-4319-82f6-6017cab4aa44" # capture transaction
"sale-086d5ae4-0619-4654-8c4f-5fffbf8f16e4" # sale transaction

Correlation IDs can be set to link requests together. For instance, if there is an online payment and the merchant's store implements their own login for generating order IDs - they may as well use that order ID as the correlation ID during the transaction journey.

Other use cases also include:

• Debugging and Troubleshooting:

  • Correlation IDs make it easier to pinpoint the source of errors in complex, distributed systems.

• Monitoring and Performance Analysis:

  • Tracking the performance of different services/operations and understand how they interact.

• Security Auditing:

  • Correlation IDs can be used to track user actions and identify potential security threats.

• Log Correlation:

  • Correlate logs from different services/operations, providing a holistic view of a request's journey.

General V4 Error Response Codes

The V4 API implements more specific response codes based on the error code from the header. This response code comes from the PayConex™ Gateway for identifying error codes more effectively in the context of the PayConex™ systems.

These codes begin at 40001.

These responses also include errorType that is specific to a Bluefin service where the error originates.

For complete json examples of these responses, see the API Reference.

Lifecycle Stages Of PayConex™ API Request

Before the transaction payload reaches the payment processor, the PayConex™ back end systems incorporate the following layers of operations that must succeed in order as illustrated in the following diagram.

These are listed by priority with their corresponding possible error types in the table above.

1. Malformed Request Validation

   🚧

   Note

   This validation ensures that the PayConex™ request does not include any malformed (or malicious) input based on the schema.

   • invalid_request

2. Authentication

   • authentication

3. Authorization

   • authorization

4. API Request Validation

   • invalid_request

5. PayConex (Back-end) Services Processing

   • service_unavailable

   • timeout

   • shieldconex_error

   • decryptx_error

   • internal_server_error

   • poi_error

   • websocket_gateway_error

   • method_not_allowed

   • not_found

🚧

transaction_error

Transaction Error typically occurs in case something goes wrong during the payment processor flow or similar.

📘

API Request Validation

This validation involves the PayConex™ services; hence the Authentication and Authorization priority.

JSONPath Validation

The PayConex™ V4 API implements JSONPath for validating JSON objects based on the schemas strictly defined for the API endpoints. These schemas can be found in the API References.

JSONPath is a tool for navigating and extracting data from JSON structures. It provides a concise and flexible syntax to access specific elements within JSON objects. In this API, it is used to determine the source of an error so that the developer knows exactly where to look and fix the request.

For example, here are some of the most common errors:

📘

Malformed Request Validation

All of these errors are returned during the Malformed Request Validation Stage above.

Property Required Error

{
  "message": "Request validation error: Does not conform to API schema.",
  "errorCode": "40001",
  "errorType": "invalid_request",
  "source": "Request",
  "value": null,
  "traceId": "0ef13be7-67bf-40c7-9c3b-40f17b894e65",
  "details": [
    {
      "source": "$.amounts.total",
      "value": null,
      "message": "Payload schema violation: property \"total\" is missing"
    }
  ]
}

Property Not Allowed/Supported

{
  "message": "Request validation error: Does not conform to API schema.",
  "errorCode": "40001",
  "errorType": "invalid_request",
  "source": "Request",
  "value": null,
  "traceId": "76cb2d8f-607a-4101-8421-32c577f155b8",
  "details": [
    {
      "source": "",
      "value": null,
      "message": "Payload schema violation: property \"credentialOnFil\" is unsupported"
    }
  ]
}

{
  "message": "Request validation error: Does not conform to API schema.",
  "errorCode": "40001",
  "errorType": "invalid_request",
  "source": "Request",
  "value": null,
  "traceId": "6474b4d4-b988-4938-aad4-598d481797af",
  "details": [
    {
      "source": "$.amounts",
      "value": null,
      "message": "Payload schema violation: property \"tota\" is unsupported"
    },
    {
      "source": "$.amounts.total",
      "value": null,
      "message": "Payload schema violation: property \"total\" is missing"
    }
  ]
}

🚧

Note

When it comes to unsupported fields, the details value is always null.

Enumeration Error

{
  "message": "Request validation error: Does not conform to API schema.",
  "errorCode": "40001",
  "errorType": "invalid_request",
  "source": "Request",
  "value": null,
  "traceId": "3380a967-d27d-4f57-acc2-e0ecfcc23367",
  "details": [
    {
      "source": "$.amounts.currency",
      "value": "EUR",
      "message": "Payload schema violation: value is not one of the allowed values [\"USD\"]"
    }
  ]
}

Regular Expression Error

{
  "message": "Request validation error: Does not conform to API schema.",
  "errorCode": "40001",
  "errorType": "invalid_request",
  "source": "Request",
  "value": null,
  "traceId": "662851fa-d46b-41aa-b6b4-e115a44ed6d9",
  "details": [
    {
      "source": "$.amounts.total",
      "value": "4.1l",
      "message": "Payload schema violation: string doesn't match the regular expression \"^\\d+(\\.\\d{0,2})?$\""
    }
  ]
}

Value Type Error

{
  "message": "Request validation error: Does not conform to API schema.",
  "errorCode": "40001",
  "errorType": "invalid_request",
  "source": "Request",
  "value": null,
  "traceId": "57a7a43c-0a58-47ee-8292-113ee80336c8",
  "details": [
    {
      "source": "$.amounts.total",
      "value": 5.11,
      "message": "Payload schema violation: value must be a string"
    }
  ]
}

{
  "message": "Request validation error: Does not conform to API schema.",
  "errorCode": "40001",
  "errorType": "invalid_request",
  "source": "Request",
  "value": null,
  "traceId": "3d5f79c3-1083-4330-bc19-1c1b9e6f353f",
  "details": [
    {
      "source": "$.amounts.total",
      "value": 5,
      "message": "Payload schema violation: value must be a string"
    }
  ]
}

Value is not nullable

In the V4 API, the null value is strictly parsed and validated.

{
  "message": "Request validation error: Does not conform to API schema.",
  "errorCode": "40001",
  "errorType": "invalid_request",
  "source": "Request",
  "value": null,
  "traceId": "be3977c9-44cb-4e49-b021-ef6a778efa35",
  "details": [
    {
      "source": "$.amounts.total",
      "value": null,
      "message": "Payload schema violation: Value is not nullable"
    }
  ]
}

Request was invalid

Ensure your JSON object is syntactically valid. For example, missing a closing }, a comma, or similar elements will result in an error in the response, pointing to where the decoding failed.

{
  "message": "Request validation error: Does not conform to API schema.",
  "errorCode": "40001",
  "errorType": "invalid_request",
  "source": "Request",
  "value": null,
  "traceId": "c9bd450b-aa8a-4344-849a-2ddfe528da58",
  "details": [
    {
      "source": "Request",
      "value": null,
      "message": "request body has an error: failed to decode request body: invalid character '\"' after object key:value pair"
    }
  ]
}

🚧

Note

Keep in mind that this error takes priority over others as it first has to parse the JSON body without any errors.

JSONPath is used in some of our other products as well. For example, ShieldConex® Orchestration.

🚧

Case Sensitive

All the field names and values are, of course, strictly validated so they are, by default, case sensitive.

For example,

JSON

{
  "message": "Request validation error: Does not conform to API schema.",
  "errorCode": "40001",
  "errorType": "invalid_request",
  "source": "Request",
  "value": null,
  "traceId": "dd87974c-8da4-449f-bcb7-f7041288cfe8",
  "details": [
    {
      "source": "",
      "value": null,
      "message": "Payload schema violation: property \"bftokenreference\" is unsupported"
    },
    {
      "source": "$.posProfile",
      "value": "eCOMMERCE",
      "message": "Payload schema violation: value is not one of the allowed values [\"MOTO\",\"ECOMMERCE\",\"SERVER\",\"ACH\"]"
    }
  ]
}

Item.Details Explanation

There are certain types of errors where we get one error at a time rather than the entire list of what's wrong with the request. For example, Request was invalid Validation throws one error at a time based on the error priority defined in the schema.

One Error

{
  "message": "Request validation error: Does not conform to API schema.",
  "errorCode": "40001",
  "errorType": "invalid_request",
  "source": "Request",
  "value": null,
  "traceId": "efd9f79b-042d-4c15-830a-65ec1c27a1ee",
  "details": [
    {
      "source": "Request",
      "value": null,
      "message": "request body has an error: failed to decode request body: invalid character '}' looking for beginning of object key string"
    }
  ]
}

Multiple Errors

If the JSONPath validates certain business logic related to the PayConex™ system, multiple errors may occur.

PayConex V4 API combines all of the API Validation Errors given that the JSON request payload was decoded correctly.

For example,

{
  "message": "Request validation error: Does not conform to API schema.",
  "errorCode": "40001",
  "errorType": "invalid_request",
  "source": "Request",
  "value": null,
  "traceId": "006918e3-640b-43e1-8a35-74b842614b26",
  "details": [
    {
      "source": "$.amounts.total",
      "value": "$4",
      "message": "Payload schema violation: string doesn't match the regular expression \"^\\d+(\\.\\d{0,2})?$\""
    },
    {
      "source": "$.bfTokenReference",
      "value": "ft_68d7a541035d4ec49bca25d9dff08a35",
      "message": "Payload schema violation: string doesn't match the regular expression \"^bft_[a-f0-9]{32}$\""
    },
    {
      "source": "$.shippingAddress",
      "value": null,
      "message": "Payload schema violation: property \"cit\" is unsupported"
    },
    {
      "source": "$.shippingAddress",
      "value": null,
      "message": "Payload schema violation: property \"stat\" is unsupported"
    },
    {
      "source": "$.shippingAddress",
      "value": null,
      "message": "Payload schema violation: property \"zi\" is unsupported"
    },
    {
      "source": "$.shippingAddress.city",
      "value": null,
      "message": "Payload schema violation: property \"city\" is missing"
    },
    {
      "source": "$.shippingAddress.state",
      "value": null,
      "message": "Payload schema violation: property \"state\" is missing"
    },
    {
      "source": "$.shippingAddress.zip",
      "value": null,
      "message": "Payload schema violation: property \"zip\" is missing"
    },
    {
      "source": "$.posProfile",
      "value": null,
      "message": "Payload schema violation: property \"posProfile\" is missing"
    }
  ]
}

In terms of priority, the following two errors are only returned given that Malformed Request Validation, Authentication, and Authorization stages all pass; this makes it the API Request Validation Stage.

{
  "message": "The bf token reference field is required when shield conex token is not present. (and 1 more error)",
  "errorCode": 40001,
  "errorType": "invalid_request",
  "source": "bfTokenReference",
  "traceId": "d2571566-f2ab-47de-8f85-40af05c8f9fc",
  "details": [
    {
      "source": "bfTokenReference",
      "message": "The bf token reference field is required when shield conex token is not present."
    },
    {
      "source": "shieldConexToken",
      "message": "The shield conex token field is required when bf token reference is not present."
    }
  ]
}

{
  "message": "This API call allows to use only one kind of token for each request (and 1 more error)",
  "errorCode": 40001,
  "errorType": "invalid_request",
  "source": "bfTokenReference",
  "value": "bft_68d7a541035d4ec49bca25d9dff08a35",
  "traceId": "f676982d-0ad6-4384-8658-8d86943b011f",
  "details": [
    {
      "source": "bfTokenReference",
      "value": "bft_68d7a541035d4ec49bca25d9dff08a35",
      "message": "This API call allows to use only one kind of token for each request"
    },
    {
      "source": "shieldConexToken",
      "value": {
        "bfid": "djE6MTIwMjAxMTEzMTE1NTA1MTAzMTAzMDQyMXxhZDhkNDQzNDhjNWVhNzc5NmMxMjVmNjZkY2Q1MDIxNHw2czdyYXp5djIvMD18U1ZUMjAxOTA0MTgxMkRFVg"
      },
      "message": "This API call allows to use only one kind of token for each request"
    }
  ]
}

References

Here are some libraries that you can use as a tool or to sharpen up your understanding of JSONPath or XPath.

NPM libraries:

• jsonpath
• xpath

Online Evaluators:

• JSONPath Online Evaluator

Checkout Component URLs

These URLs are essential for loading and displaying the Checkout Component.

Account Updater API Endpoints

Webhook Services

The PayConex™ Webhook service allows a developer to create a webhook that receives real-time notifications when tokens or card accounts are updated by the card issuers.

Registering a Webhook

This endpoint allows a developer to create a webhook.

Endpoint(s)

/api/v4/accounts/{accountId}/webhooks

HTTPS Method(s)

Triggering a Webhook

This endpoint allows a developer to trigger a webhook manually to make sure it is working properly. This can only be triggered by the event name of PAYCONEX_BATCH_SETTLEMENT.

Endpoint(s)

/api/v4/webhooks/trigger

HTTPS Method(s)

Managing a Webhook

This endpoint allows a previously configured webhook to be retrieved, modified or removed.

Endpoint(s)

/api/v4/accounts/{accountId}/account-updater/webhooks/{webhookID}

HTTPS Method(s)

If you would like to read more about these functions and see some example request/response information, see our guide on Setting up and Managing Webhooks.

Card Subscription Services

A PayConex™ Account Updater subscription is an object that contains an array of token data or card data along with instructions on how frequently PayConex™ should update the card data on file.

📘

Note

The term subscription in this context is not tied to a recurring payment schedule within PayConex™. In this context, it means you are 'subscribing' token data or card data to be updated on a set schedule.

The PayConex™ account updater service does work natively with the recurring payment schedules in PayConex™. If you're interested in using PayConex™ for recurring payments, see our guide on how to Schedule Transactions.

Creating a Subscription

These endpoints allow a developer to subscribe a customer's stored token or card data for continuous updates by the card issuers.

When a subscription is created, PayConex™ issues the token or card data records for updates on a set schedule. The records and schedule are defined as part of the API request body.

PayConex™ tokens (transaction identifiers) can be sent through the payconex/subscribe endpoint, PAN data through the pan/subscribe endpoint, and ShieldConex® tokens using the shieldconex/subscribe endpoint.

Endpoint(s)

/api/v4/accounts/{accountId}/account-updater/payconex/subscribe
/api/v4/accounts/{accountId}/account-updater/pan/subscribe
/api/v4/accounts/{accountId}/account-updater/shieldconex/subscribe

HTTPS Method(s)

If you would like to read more about these functions and see some example request/response information, see our guide on Creating Subscriptions.

Managing a Subscription

This endpoint allows a developer to retrieve or change the details of or delete a previously set up account updater subscription.

Endpoint(s)

/api/v4/accounts/{account}/account-updater/subscriptions/{subscriptionId}

HTTPS Method(s)

Removing Individual Token or Card Records from a Subscription

This endpoint allows a specific record that is part of an account updater subscription to be removed.

Endpoint(s)

/api/v4/accounts/{account}/account-updater/subscriptions/{subscriptionId}/records/{recordId}

HTTPS Method(s)

Adding Individual Token or Card Records to a Subscription

These endpoints allow new tokens or cards to be added to an existing subscription using a subscriptionId.

PayConex™ tokens can be sent through the payconex/subscribe endpoint, PAN information through the pan/subscribe endpoint, and ShieldConex® tokens using the shieldconex/subscribe endpoint.

Endpoint(s)

/api/v4/accounts/{account}/account-updater/subscriptions/{subscriptionId}/payconex
/api/v4/accounts/{account}/account-updater/subscriptions/{subscriptionId}/shieldconex
/api/v4/accounts/{account}/account-updater/subscriptions/{subscriptionId}/pan

HTTPS Method(s)

If you would like to read more about these functions and see some example request/response information, see our guide on Managing a Subscription.

Retrieving Account Updater Results

Getting Subscription Details

This endpoint returns the full details of a subscription. The id of a previous subscription request or response is used as the scheduleId.

Endpoint(s)

/api/v4/accounts/{account}/account-updater/schedules/{scheduleId}/results

HTTPS Method(s)

Getting Updates

After configuring a webhook and an account updater subscription, PayConex™ issues notifications to the webhook URL provided. When a webhook notification is received, this endpoint can be used with the resulting updateId to retrieve all updates associated with the webhook notification.

Endpoint(s)

/api/v4/accounts/{account}/account-updater/updates/{updateId}

HTTPS Method(s)

If you would like to read more about these functions and see some example request/response information, see our guide on Retrieving Card Updates.