Payments: Token

Modified on Wed, 12 Apr, 2023 at 1:05 PM

Card Token Generation

To enforce best practices for online PCI compliance and simultaneously provide ease of use, ACME enables tokenization of card transactions, which removes any storage of card information from a checkout upon generation.  

Tokens allow not just single use but repeat customer use cases for both sales and refunds.


You will need a PaymentKey, passed as an HTTP request header into the get token API. Additionally, during the onboarding, we will white list those calls to only be allowed from your top-level domain and subdomains by taking advantage of the browser cross-origin (CORS) domain permissions. 

x-acme-payment-key

For any machine to machine calls, use the platform private API key supplied during the onboarding.

Generate a Single Use Token

Generate a token that can be used one time.

POST v1/payment/{mid}/tokens/singleuse

HTML

Generate a token using the CORS infrastructure 

POST v1/payment/{mid}/cors/tokens/singleuse

HTML

  

Request Parameters

The merchant id (mid) of the seller that a token is being generated for.

Request Body

A Token object containing the credit card information you want the token for.  

Sample Request

POST https://sandX-api.acmepayments.net/v1/payment/12345/tokens/singleuse

HTML

Sample Request Body

This is a n example PaymentToken object. 

{
"paymentMethod": "creditCard",
"card": {
"pan" : "5454545454545454",
"expirationDate" : {
"month" : "12",
"year" : "2023"
},
"cvc" : "123",
"postalCode": "T1X 0V6"
},
"externalCustomerId": "CID-123",
"externalPaymentMethodId": "PMID-123",
"validate": false
}

XML

Response

A Token object that can be used a single time.

Generate a Card on File Token

Generate a token that can be use multiple times.

POST v1/payment/{mid}/tokens/card

HTML

 

Request Parameters

The merchant id (mid) of the seller that a token is being generated for.

Request Body

A Token object containing the credit card information you want the token for.  

Sample Request

POST https://sandX-api.acmepayments.net/v1/payment/12345/tokens/card

HTML

Response

A sample response:

{
"token": "9c2bce81-bf56-4ec6-ae76-5e9a476c181c",
"paymentMethod": "CreditCard",
"type": "multiple",
"card": {
"lastFour": "4242",
"expirationDate": {
"month": "12",
"year": "2023"
},
"cvc": "123",
"postalCode": "T1X 0V6",
"brand": "Visa",
"firstName": "John",
"lastName": "Smith"
},
"externalCustomerId": "CID-123",
"externalPaymentMethodId": "PMID-123",
"validate": false
}

XML

Retrieving a Token by ID

Returns a token

GET v1/payment/{mid}/tokens/{token}

HTML

 

Request Parameters

The {mid} is the merchant Id of the seller that the token is associated with.
The {token} in the URL of the request. The token was returned in a successful  token generation call.

Sample Request

GET https://sandX-api.acmepayments.net/v1/payment/12345/tokens/9c2bce81-bf56-4ec6-ae76-5e9a476c181c

HTML

Response

A Token object.

Retrieving a Token by External Payment Method ID

Returns a token associated with an External payment method ID

GET v1/payment/{mid}/tokens/ext/{externalPaymentMethodId}

HTML

 

Request Parameters

The {mid} is the merchant ID of the seller that the token is associated with.

The {externalPaymentMethodId} in the URL of the request. The externalPaymentMethodId was supplied in the  token generation call.

Sample Request

GET https://sandX-api.acmepayments.net/v1/payment/12345/tokens/ext/PMID-123

HTML

Response

Retrieving a List of Card on File Tokens by External Customer Id

Returns a list of Card on File tokens associated with this external customer.

GET v1/payment/{mid}/customer/ext/{externalCustomerId}/card

HTML

 

Request Parameters

The {mid} is the merchant Id of the seller that the token is associated with.

The {externalCustomerId} in the URL of the request. The externalCustomerId was supplied in the  token generation call.

Query String Parameters

Field

Type

Description

Default

page

number

The page that you want to retrieve

1st page

pageSize

number

The number of transactions to return per page. Maximum is 500 pages.If a larger number is entered, it will be reduced to 500.

100 pages

sortDirection

string

Results sorting direction (“asc” or “desc”)

ascending

sortField

string

Field to sort on. CreatedOn is the only supported field.

createdOn

Sample Request

GET https://sandX-api.acmepayments.net/v1/payment/12345/customer/ext/CID-123/card

HTML

Response

A List of Token objects.

{
"list": [
{
"token": "9c2bce81-bf56-4ec6-ae76-5e9a476c181c",
"paymentMethod": "CreditCard",
"type": "multiple",
"card": {
"lastFour": "4242",
"expirationDate": {
"month": "12",
"year": "2023"
},
"cvc": "123",
"postalCode": "T1X 0V6",
"brand": "Visa",
"firstName": "John",
"lastName": "Smith"
},
"externalCustomerId": "CID-123",
"externalPaymentMethodId": "PMID-123"
},
{
"token": "9c2bce81-bf56-4ec6-ae76-5e9a476c181c",
"paymentMethod": "CreditCard",
"type": "multiple",
"card": {
"lastFour": "4242",
"expirationDate": {
"month": "12",
"year": "2023"
},
"cvc": "123",
"postalCode": "T1X 0V6",
"brand": "Visa",
"firstName": "John",
"lastName": "Smith"
},
"externalCustomerId": "CID-123",
"externalPaymentMethodId": "PMID-123"
}
],
"pagination": {
"page": 1,
"pageSize": 2,
"sortDirection": "asc",
"sortField": "createdOn",
"hasMore": true
}
}

XML

Delete a Token by ID

Deletes a token

DELETE v1/payment/{mid}/tokens/{token}

HTML

 

Request Parameters

The {mid} is the merchant ID of the seller that the token is associated with.

The {token} in the URL of the request. The token was returned in a successful token generation call.

Sample Request

DELETE https://sandX-api.acmepayments.net/v1/payment/12345/tokens/9c2bce81-bf56-4ec6-ae76-5e9a476c181c

HTML

Response

The deleted Token object.

Delete a Token by External Payment Method ID

Deletes a token associated with an External Payment Method ID

DELETE v1/payment/{mid}/tokens/ext/{externalPaymentMethodId}

HTML

 

Request Parameters

The {mid} is the merchant ID of the seller that the token is associated with.

The {externalPaymentMethodId} in the URL of the request. The externalPaymentMethodId was supplied in the  token generation call.

Sample Request

DELETE https://sandX-api.acmepayments.net/v1/payment/12345/tokens/ext/PMID-123

HTML

Response

The deleted Token object.

Token Object

Name

Type

Description

Required

token

string

A unique token used to make the sale

Read Only

type

string

The type of token it is ‘single’ or ‘multiple’. 

Read Only

paymentMethod

string

The type of payment method.  Currently we only support ‘creditCard’, future might include values like ‘ach'

Required

card

Card Object

The card information. Used to create the payment method during token generation. Responses containing the payment method will not contain the card pan.

 Required

externalCustomerId

string

Plain text value provided for this token.  Max 255 char. Cannot contain %, <, >, http:, https:, /, \\

Optional

externalPaymentMethodId

string

Plain text value provided for this token.  Must be unique; Max 255 char. Cannot contain %, <, >, http:, https:, /, \\

Optional

validate

Boolean

Select to validate the card when the token is generated.  Only applicable when creating a card on file. Setting 'false' bypasses processor validation. Default is 'false'.  This is not returned in the list call.

Optional

Card Object

Name

Type

Description

Required

pan

string

The entire credit card number.  Only in request object.

Required

lastFour

string

Last four digits of the credit card on file

Read Only

expirationDate

object

Expiration date of the credit card on file

Required

expirationDate.month

string

Required

expirationDate.year

string

Required

cvc

string

The cvc of the card.  Only available in the token generation API calls.

Required

postalCode

string

The zip code for the billing address of the card. When passed it will be passed through. Validation of the postal code to CC billing address takes place in the sale transaction call.  Error will be returned if postal code does not match the cards postal code.

This is not available during a Card Present workflow.

Optional

brand

string

Brand of the credit card on file

Read Only

firstName

string

First name of the cardholder.  Automatically returned if available.  It will not be returned in transactions that were processed by token without a card present.

Read Only

lastName

string

Last name of the cardholder. Automatically returned if available.  It will not be returned in transactions that were processed by token without a card present.

Read Only



Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article