Payments: Token

Modified on Wed, 12 Apr 2023 at 01: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