Tokenizes a payment card and its billing address so the card can be charged later without transmitting raw card data again. Use this endpoint to support saved payment methods, card on file billing, and repeat purchases while reducing PCI scope.
Warning: network_token_data is returned only when network tokenization is enabled for your account. Contact SoftPoint to have this feature enabled before integrating against the network token response fields.
Request Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer YOUR_ACCESS_TOKEN |
| Content-Type | Yes | application/json |
Request Parameters
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| location_id | string | Yes | Identifier of the location. |
Request Body Fields
| Field | Type | Required | Description |
|---|---|---|---|
| user_id | string | Yes | Identifier of the customer the token belongs to. |
| currency_iso | string | Yes | ISO currency code, for example USD. |
| phone_number | string | No | Customer phone number. |
| msisdn | string | No | Mobile subscriber number associated with the customer. |
| country_iso | string | No | ISO country code for the customer. |
| card_data | object | Yes | Card details to tokenize. |
| card_data.pan | string | Yes | Card primary account number. Must not exceed 16 digits. |
| card_data.exp_month | string | Yes | Card expiration month, two digits. |
| card_data.exp_year | string | Yes | Card expiration year, two digits. |
| card_data.card_holder | string | Yes | Name of the cardholder. |
| card_data.card_type | string | No | Card brand, for example Visa. |
| billing_address | object | No | Billing address associated with the card. |
| billing_address.street | string | No | Street address. |
| billing_address.street_2 | string | No | Secondary address line. |
| billing_address.zip | string | No | Postal code. |
| billing_address.city | string | No | City. |
| billing_address.state | string | No | State or region. |
| billing_address.email | string | No | Email address for the billing contact. |
Request Example
{
"user_id": "5001",
"currency_iso": "USD",
"phone_number": "9825065185",
"country_iso": "US",
"card_data": {
"pan": "4111111111111111",
"exp_month": "10",
"exp_year": "30",
"card_holder": "John Doe"
},
"billing_address": {
"street": "516 Pine Dr",
"street_2": "Street 2",
"zip": "50020",
"city": "boston",
"state": "CA",
"email": "[email protected]"
}
}
cURL Example
curl --request POST \
--url https://sandbox-gtw.softpoint.io/api/locations/YOUR_LOCATION_ID/tokens \
--header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"user_id": "5001",
"currency_iso": "USD",
"country_iso": "US",
"card_data": {
"pan": "4111111111111111",
"exp_month": "10",
"exp_year": "30",
"card_holder": "John Doe"
},
"billing_address": {
"street": "516 Pine Dr",
"zip": "50020",
"city": "boston",
"state": "CA",
"email": "[email protected]"
}
}'
Success Response
{
"network_token_data": {
"token": "4895370019917092",
"exp_month": "12",
"exp_year": "34",
"card_network": "visa",
"state": "ACTIVE"
},
"servicefee_amount": 0,
"surcharge_amount": 0,
"tip_amount_approved": 0,
"conveniencefee_amount": 0,
"authcode": "016150703802094",
"approvalCode": "831000",
"networkTransactionId": "016150703802094",
"reference_id": "",
"currency_iso": "USD",
"inv_number": "",
"networkReconciliationId": "L3MHGQW5W1MG",
"avsCode": "Y",
"avsCodeRaw": "Y",
"cardVerification": "",
"cardVerificationRaw": "",
"transaction_id": "756F11F1-E1E1-4724-A0D8-D05099D6021D",
"transaction_no": "016150703802094",
"card_data": {
"token": "GRYfiyggFSBV0670",
"cardfullname": "John Doe",
"expiry_information": "10/30",
"last4": "0670",
"card_brand": "Visa"
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
| network_token_data | object | Network token information returned when network tokenization is enabled, contact SoftPoint to enable it. |
| network_token_data.token | string | Network token (DPAN) issued by the card network. |
| network_token_data.exp_month | string | Network token expiration month in MM format. |
| network_token_data.exp_year | string | Network token expiration year in YY format. |
| network_token_data.card_network | string | Card network associated with the network token, for example visa. |
| network_token_data.state | string | Current status of the network token, for example ACTIVE. |
| servicefee_amount | number | Service fee amount applied to the transaction. |
| surcharge_amount | number | Surcharge amount applied to the transaction. |
| tip_amount_approved | number | Approved tip amount. |
| conveniencefee_amount | number | Convenience fee amount applied to the transaction. |
| authcode | string | Authorization code returned during tokenization. |
| approvalCode | string | Approval code returned by the processor. |
| networkTransactionId | string | Network transaction identifier assigned by the card network. |
| reference_id | string | Reference identifier, when present. |
| currency_iso | string | Currency associated with the token. |
| inv_number | string | Invoice number associated with the transaction, when provided. |
| networkReconciliationId | string | Identifier used by the card network for reconciliation. |
| avsCode | string | Normalized Address Verification Service (AVS) result code. |
| avsCodeRaw | string | Raw AVS response code returned by the processor. |
| cardVerification | string | Normalized card verification (CVV/CVC) result code, when available. |
| cardVerificationRaw | string | Raw card verification response code returned by the processor. |
| transaction_id | string | Identifier of the tokenization transaction. |
| transaction_no | string | Gateway transaction number. |
| card_data | object | Tokenized card summary. |
| card_data.token | string | The gateway token representing the stored card. Use this value for future card-on-file transactions. |
| card_data.cardfullname | string | Cardholder name. |
| card_data.expiry_information | string | Card expiry in MM/YY format. |
| card_data.last4 | string | Last four digits of the card. |
| card_data.card_brand | string | Card brand. |
Error Responses
Validation Error
Returned when the card number exceeds the permitted length.
{
"message": "The card data.pan field must not have more than 16 digits.",
"errors": {
"card_data.pan": [
"The card data.pan field must not have more than 16 digits."
]
}
}
Status Codes
| Code | Description |
|---|---|
| 200 | Token created successfully. |
| 401 | Missing or invalid access token. |
| 422 | Validation failed, for example an invalid PAN length. |
Workflow Placement
Create Token enables card-on-file processing:
-
Generate a gateway access token.
-
Tokenize the card with this endpoint.
-
Use the returned token in Sale or Authorize, or manage it through Get, Update, and Delete Token.
Notes
-
The gateway token is returned in
card_data.token. Persist this value to charge the card later. -
When available,
network_token_datacontains the network token (DPAN) and its metadata returned by the card network. This information is provided for reference and network token lifecycle management. -
The PAN must not exceed 16 digits, or the request is rejected with HTTP 422.
-
Validation errors on this endpoint use a
messageanderrorsstructure rather than the standard error envelope.
Common Mistakes
-
Submitting a PAN longer than 16 digits.
-
Confusing the gateway token (
card_data.token) with the network token (network_token_data.token). The gateway token should be used for subsequent API requests unless your integration specifically requires the network token. -
Expecting the standard error envelope for validation failures, which instead use
messageanderrors. -
Failing to persist the returned gateway token, which is required for subsequent charges.