> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Create token from FPAN
> Import cardholder-data in exchange for a Commerce token.
In order to use this endpoint you need to prove a certain level of compliance with PCI DSS with us.
Reach out to your account manager for more information.
Gated Feature
## OpenAPI
````yaml /products/commerce/v2/openapi.yaml post /cde-import
openapi: 3.1.0
info:
title: Commerce API
version: '2.0'
description: >
The Commerce V2 API provides a comprehensive payment orchestration platform
designed to streamline and optimize payment processing for modern
businesses.
Built with flexibility and security at its core, our API enables you to
process payments, manage authentications, and handle cardholder data across
multiple payment processors without vendor lock-in.
contact:
name: Starfish GmbH & Co. KG
email: hello@starfish.team
url: https://hellgate.io/cpa/commerce
license:
name: Commerce API Terms
url: https://hellgate.io/terms-and-conditions
servers:
- url: https://sandbox.hellgate.io
description: Commerce SaaS Sandbox
- url: https://api.hellgate.io
description: Commerce SaaS Production
security: []
tags:
- name: payments_ci
description: >-
Handle payment processing where the customer is actively present and
authorizing the transaction.
- name: payments_mi
description: >-
Process transactions without direct customer interaction at the time of
payment.
- name: payments_modifications
description: >-
Modify existing payment transactions after initial authorization (capture,
void, refund).
- name: payments_data
description: >-
Access comprehensive payment transaction data for reporting,
reconciliation, and analysis.
- name: refunds_data
description: Access detailed refund transaction data for tracking and reconciliation.
- name: authentications_ci
description: >-
Process EMVCo 3-D Secure authentication requests as standalone
transactions (one-off, recurring, installment).
- name: authentications_mi
description: >-
Process requestor-initiated EMVCo 3-D Secure authentication requests (3RI)
as standalone transactions.
- name: authentications_data
description: Access the results of prior authentications for reference.
- name: credentials_management
description: >-
Manage stored payment credentials for repeat customers across all
operating models.
- name: tokens_create
description: >-
Create and import Commerce tokens to securely store cardholder data while
maintaining PCI DSS compliance.
- name: tokens_management
description: Manage stored Commerce tokens including CVC2 security code management.
- name: compliance_service
description: >-
Safely handle sensitive cardholder data while maintaining PCI DSS
compliance via a secure proxy service.
- name: network_tokens
description: >-
Manage network tokens with major card schemes with automatic lifecycle
management.
- name: merchants
description: >-
Configure and manage merchant accounts based on your chosen operating
model.
- name: reconciliation
description: Reconcile imported token data.
- name: processor_backup
description: >-
Migrate payment tokens from third-party processors (currently supports
stripe.com).
paths:
/cde-import:
post:
tags:
- tokens_create
summary: Create token from FPAN
description: |
Import cardholder-data in exchange for a Commerce token.
In order to use this endpoint you need to prove a certain level of compliance with PCI DSS with us.
Reach out to your account manager for more information.
operationId: import_cardholder_data
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CardholderData'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/HellgateToken'
'401':
$ref: '#/components/responses/401_UnauthorizedError'
'422':
$ref: '#/components/responses/422_ValidationError'
security:
- APIKeyAuth: []
components:
schemas:
CardholderData:
type: object
properties:
cardholder_name:
type: string
description: The name of the cardholder
example: Jane Holder
expiry_month:
type: integer
description: The expiry month of the card
minimum: 1
maximum: 12
example: 4
expiry_year:
type: integer
description: The expiry year of the card
minimum: 2000
example: 2025
account_number:
type: string
description: The card number (without separators)
example: '4111111111111111'
security_code:
type: string
minLength: 3
maxLength: 4
description: |
The security code of the card
The system will not permanently store the security code, but keep it in a ephemeral position for immediate use.
example: '123'
required:
- account_number
- expiry_month
- expiry_year
HellgateToken:
type: object
properties:
id:
type: string
description: The ID of the Commerce Token
format: uuid
cardholder_name:
type: string
description: The name of the owner of the card
card_art_url:
type: string
description: The url linking to the card art endpoint
created_at:
type: string
description: The date-time the payment-method was created (following ISO 8601)
format: date-time
expiry_month:
type: integer
description: The number of month in a year (e.g. April is 4)
expiry_year:
type: integer
description: The year given as four digit number (e.g. 2023)
expires_at:
type: string
description: >
The date-time when the token will expire. Applicable only for
ephemeral tokens.
format: date-time
invalidated_at:
type: string
format: date-time
description: >
The time the Commerce Token was invalidated, because the underlying
payment instrument was invalidated by the scheme.
issuer_identification_number:
type: string
description: The issuer idenfication number (IIN) - also known as BIN
account_number_last_four:
type: string
description: Last four digits of the card number
account_number_length:
type: integer
description: The total number of digits in the card number
masked_account_number:
type: string
description: >
The full lenght of the card number, but masked to conform to PCI DSS
requirments
bank_name:
type: string
description: >
The name of the issuing bank.
This information is present if metadata inquiries are active for
your account.
segment:
type: string
description: >
The segment or category of the card.
This information is present if metadata inquiries are active for
your account.
enum:
- consumer
- commercial
status:
type: string
description: The status of this Commerce token.
enum:
- active
- invalid
type:
type: string
description: >
The funding type of the card.
This information is present if metadata inquiries are active for
your account.
enum:
- credit
- debit
- prepaid
- charge
- deferred
- unknown
currency_code:
type: string
description: >
The three letter currency code of the card.
See: [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)
This information is present if metadata inquiries are active for
your account.
minLength: 3
maxLength: 3
country_code:
$ref: '#/components/schemas/ISO3166-2-CountryCode'
network_token_status:
$ref: '#/components/schemas/NetworkTokenStatus'
network_token_status_reason:
$ref: '#/components/schemas/NetworkTokenStatusReason'
scheme:
$ref: '#/components/schemas/CardScheme'
identity_and_verification:
type: string
description: >
The type of ID&V submitted during the creation of the Commerce
token..
enum:
- none
- checked
- skipped
authentication_data:
$ref: '#/components/schemas/HellgateTokenAuthenticationData'
supports_device_binding:
type: boolean
business_key:
type: string
description: >
This attribute holds the original business key under which the
cardholder data was stored on the system from which it was imported
to Commerce.
It can be used for reconciliation or reference purposes.
import_provider:
type: string
description: >
The source from which the cardholder data was imported from.
The `business_key` attribute will refer to the original ID at this
provider.
required:
- id
- created_at
- expiry_month
- expiry_year
- masked_account_number
- issuer_identification_number
- scheme
example:
id: 5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d
cardholder_name: John Doe
card_art_url: >-
https://api.hellgate.io/tokens/card-art/374c911a-8125-40eb-acb8-a26efd25f02b
created_at: '2023-10-01T00:00:00Z'
expiry_month: 4
expiry_year: 2033
expires_at: '2023-10-07T00:00:00Z'
issuer_identification_number: '424242'
masked_account_number: 424242******4242
network_token_status: active
scheme: VISA
ISO3166-2-CountryCode:
type: string
description: |
A two letter country code.
[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
NetworkTokenStatus:
type: string
description: >
The status of the associated network token.
| **Status** | **Description** |
|------------|---------------------------------------------------------------------------------------------------------------------|
| `active` | The network token is active and can be used. |
| `inactive` | The network token is inactive, which prevents using it.
The reason can be for example suspended network token. |
| `pending` | A network token is currently being provisioned. As soon as
this is available, the status is changed to `active`.
| `failed` | A network token failed to be provisioned.
| `deleted` | The network token is deleted and cannot be used again.
It is also not possible to activate the network token again. |
| `not_available` | A network token can not be provisioned with the
current configuration. |
enum:
- active
- inactive
- pending
- deleted
- failed
- not_available
NetworkTokenStatusReason:
type: object
properties:
scheme_code:
type: integer
description: The code returned by the Scheme Network
classifier:
type: string
description: Technical code that helps to identify the error
message:
type: string
description: >
The error message describing why the network token failed during the
Network Token creation in Scheme Network.
CardScheme:
type: string
description: The scheme in which the card was issued
enum:
- VISA
- Mastercard
- American Express
- Discover
- Diners Club
- JCB
- UnionPay
- Unknown
HellgateTokenAuthenticationData:
type: object
properties:
acs_transaction_id:
type: string
description: The ID of the transaction of the access control server.
format: uuid
transaction_status:
deprecated: true
type: string
description: |
The status of Authentication Transaction
Transaction Statuses:
* `Y` - Authentication / Account verified with success
* `N` - Not authentication / Account not verified
* `U` - Authentication / Account verification not available
* `A` - Payment Attempt Processed: Authentication not confirmed, but verification attempted
* `C` - Challenge required
* `R` - Authentication / Account verification has been rejected
* `D` - Challenge required via Decoupled Authentication
* `I` - Informational only
status:
type: string
description: |
The status of Authentication Transaction
Transaction Statuses:
* `Y` - Authentication / Account verified with success
* `N` - Not authentication / Account not verified
* `U` - Authentication / Account verification not available
* `A` - Payment Attempt Processed: Authentication not confirmed, but verification attempted
* `C` - Challenge required
* `R` - Authentication / Account verification has been rejected
* `D` - Challenge required via Decoupled Authentication
* `I` - Informational only
transaction_status_reason:
deprecated: true
type: string
description: |
The additional information about why the Transaction Status has the
specified value
Transaction Status Reasons:
* `01` - Card authentication failed
* `02` - Unknown Device
* `03` - Unsupported Device
* `04` - Exceeds authentication frequency limit
* `05` - Expired card
* `06` - Invalid card number
* `07` - Invalid transaction
* `08` - No Card record
* `09` - Security failure
* `10` - Stolen card
* `11` - Suspected fraud
* `12` - Transaction not permitted to cardholder
* `13` - Cardholder not enrolled in service
* `14` - Transaction timed out at the ACS
* `15` - Low confidence
* `16` - Medium confidence
* `17` - High confidence
* `18` - Very High confidence
* `19` - Exceeds ACS maximum challenges
* `20` - Non-Payment transaction not supported
* `21` - 3RI transaction not supported
* `22` - ACS technical issue
* `23` - Decoupled Authentication required by ACS but not requested by 3DS Requestor
* `24` - 3DS Requestor Decoupled Max Expiry Time exceeded
* `25` - Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt
* `26` - Authentication attempted but not performed by the cardholder
status_reason_code:
type: string
description: |
The additional information about why the Transaction Status has the
specified value
Transaction Status Reasons:
* `01` - Card authentication failed
* `02` - Unknown Device
* `03` - Unsupported Device
* `04` - Exceeds authentication frequency limit
* `05` - Expired card
* `06` - Invalid card number
* `07` - Invalid transaction
* `08` - No Card record
* `09` - Security failure
* `10` - Stolen card
* `11` - Suspected fraud
* `12` - Transaction not permitted to cardholder
* `13` - Cardholder not enrolled in service
* `14` - Transaction timed out at the ACS
* `15` - Low confidence
* `16` - Medium confidence
* `17` - High confidence
* `18` - Very High confidence
* `19` - Exceeds ACS maximum challenges
* `20` - Non-Payment transaction not supported
* `21` - 3RI transaction not supported
* `22` - ACS technical issue
* `23` - Decoupled Authentication required by ACS but not requested by 3DS Requestor
* `24` - 3DS Requestor Decoupled Max Expiry Time exceeded
* `25` - Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt
* `26` - Authentication attempted but not performed by the cardholder
ErrorGeneric:
type: object
properties:
code:
$ref: '#/components/schemas/ErrorStatusCode'
classifier:
$ref: '#/components/schemas/ErrorClassifier'
message:
$ref: '#/components/schemas/ErrorMessage'
ErrorValidation:
type: object
properties:
code:
$ref: '#/components/schemas/ErrorStatusCode'
classifier:
$ref: '#/components/schemas/ErrorClassifier'
message:
$ref: '#/components/schemas/ErrorMessage'
validation_errors:
type: array
items:
type: object
properties:
path:
type: string
description: Json-path in the request which points to the validation error
message:
type: string
description: Human readable validation message
ErrorStatusCode:
type: integer
description: The corresponding HTTP status code for the error
ErrorClassifier:
type: string
description: Technical code that helps to identify the error
ErrorMessage:
type: string
description: Human readable representation of the error
responses:
401_UnauthorizedError:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorGeneric'
example:
code: 401
message: No valid means of authentication was provided
classifier: UNAUTHORIZED
422_ValidationError:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorValidation'
example:
code: 422
classifier: VALIDATION_ERROR
message: Validation error
validation_errors:
- path: json-path
message: human readable error message
securitySchemes:
APIKeyAuth:
type: apiKey
name: X-API-Key
in: header
````