PCI Transaction API
We're currently working on improving this page to provide you with the best possible experience. Please bear with us while we make some changes.
Thank you for your patience!
This API enables PCI-compliant merchants to send transactions containing card data directly, without requiring them to use the payment.js tokenization or hosted payment page.
The API solely supports card transactions. For any other kind of payment method (e.g. PayPal, DirectDebit etc.) please refer to the regular Transaction API.
If you are already familiar with the regular API, you will notice that the only
change is the addition of the cardData
element. Everything else behaves the same.
To access the PCI API, we require some documentation from merchants. This process takes some time, so please plan accordingly.
Here are the steps to enable the PCI API:
- Create a support ticket at [email protected], providing the following information:
- Request for the system (production or sandbox)
- Related merchant guid — which looks like
ME-0123-4567-890a-bcde-f012-3456
- PCI compliance evidence
- As PCI compliance evidence, we only accept:
- Official SAQ-D or AOC documents. QSA certificates are not accepted, see PCI requirements.
- The document must not be be expired.
- The document must be signed.
- The document must be complete with no pages missing.
- The merchant's name used in the document and in the IXOPAY platform must be the same.
- It is acceptable if the names do not match in the case where a payment gateway provides your AOC or SAQ-D and sends us transactions on your behalf, as long as you inform us in advance.
Please note that we keep track and document who we've granted the PCI API for and when. We also require to review the SAQ-D or AOC when it expires and reserve the right to revoke the permission for the PCI API.
You can expect a response from our team within approximately 2 days after submitting your application for review.
Thank you for your cooperation. We take PCI compliance seriously, and these requirements ensure that we maintain the highest level of security for our platform and our merchants.
Getting started
- Endpoint:
https://secure.ixopay.com/api/v3
- Full OpenApi 3.0 Specification: https://secure.ixopay.com/Schema/V3/OpenApiSpecificationDirectPCI.yml
Any values inside curly braces {
}
should be replaced with the actual values without the curly braces, for example:
secure.ixopay.com/api/v3/transaction/{apiKey}/debit → secure.ixopay.com/api/v3/transaction/yourApiKey/debit
Request format
Requests are sent via HTTPS containing a JSON body.
- The server accepts TLS version ≥ 1.2 connections.
- Content-Type must be
application/json
- Authentication credentials are sent via BASIC Auth (see below)
- The request must contain a valid signature within the
X-Signature
header (see below) - The request must contain a valid
Date
header, because this value is used for signature verification (refer to RFC 7231)
To test the DirectPCI API in the Sandbox environment add following header to your request:
X-Environment: Sandbox
Headers Example:
Content-Type: application/json; charset=utf-8
Date: Mon, 01 Jan 2018 11:01:36 UTC
Authorization: Basic YW55QXBpVXNlcjpteVBhc3N3b3JkCg==
X-Signature: DH7MfiGq5QYQusTzWMpWiJpnPz+o1pZbcf7HCiT1+jjc+7UrnmDSpVuHzrRrZ6UxJUYYnOHJfG91zm0VimWXHg==
Authentication
To authenticate API requests, the API username and password must be sent as BASIC Authentication in the Authorization
header,
as defined in RFC 7617.
To achieve this, the username and password are first concatenated with a :
(colon) separator,
and the resulting string is then Base64 encoded. Here is an example of how this process works:
- Suppose the API username is
anyApiUser
and the password ismyPassword
. - Concatenate the username and password with a
:
separator:anyApiUser:myPassword
. - Base64 encode the concatenated string:
YW55QXBpVXNlcjpteVBhc3N3b3JkCg==
. - Finally, include the
Authorization
header in the API request with the Base64 encoded string, like so:Authorization: Basic YW55QXBpVXNlcjpteVBhc3N3b3JkCg==
.
Many programming frameworks will automatically handle the BASIC Authentication process for you once you provide the username and password to the appropriate request object.
Signature
We highly encourage our users to take advantage of the additional security measures we offer. One such measure involves verifying the authenticity of responses through signature verification. For further details on how to implement this security feature, we recommend reviewing our comprehensive guide to Additional security.