TABLE OF CONTENTS



Server Side Token call


Depending on your integration type as it related to PCI considerations, you will either want to get a card token from the browser so that your servers never see the light of a card PAN (Personal Account Number) or get a card token from the server if you accept having your servers see PAN.


In the event you decide on a browser-originated integration to get the token, during the platform onboarding process, we will give you a publishable key to be 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. See another example of a CORS acme API here.

x-acme-payment-key


In the event of opting for a server to server call, then , as any such call, you will use the platform private API key supplied during the platform onboarding.


Generate a Single Use Token

Generate a token that can be use one time.

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

 

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.acmeticketing.net/v1/payment/987-654-321/tokens/singleuse


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

 

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.acmeticketing.net/v1/payment/987-654-321/tokens/card


Response

A Token object that can be used multiple times.


Retrieving a Token by ID

Returns a token

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

 

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.acmeticketing.net/v1/payment/987-654-321/tokens/9c2bce81-bf56-4ec6-ae76-5e9a476c181c


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}

 

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.acmeticketing.net/v1/payment/987-654-321/tokens/ext/PMID-123


Response

A Token object.


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

 

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

FieldTypeDescriptionDefault
pagenumberThe page that you want to retrieve1st page
pageSizenumberThe 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
sortDirectionstringResults sorting direction (“asc” or “desc”)ascending
sortFieldstringField to sort on. CreatedOn is the only supported field.createdOn


Sample Request

GET https://sandX-api.acmeticketing.net/v1/payment/987-654-321/customer/ext/CID-123/card


Response

A List of Token objects.



Delete a Token by ID

Deletes a token

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

 

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.acmeticketing.net/v1/payment/987-654-321/tokens/9c2bce81-bf56-4ec6-ae76-5e9a476c181c


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}

 

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.acmeticketing.net/v1/payment/987-654-321/tokens/ext/PMID-123


Response

The deleted Token object.



Token Object

NameTypeDescriptionRequired
tokenstringA unique token used to make the saleRead Only
typestringThe type of token it is ‘single’ or ‘multiple’. Read Only
paymentMethodstringThe type of payment method.  Currently we only support ‘creditCard’, future might include values like ‘ach'Required
cardCard ObjectThe card information. Used to create the payment method during token generation. Responses containing the payment method will not contain the card pan. Required
externalCustomerIdstringPlain text value provided for this token.  Max 255 char. Cannot contain %, <, >, http:, https:, /, \\Optional
externalPaymentMethodIdstringPlain text value provided for this token.  Must be unique; Max 255 char. Cannot contain %, <, >, http:, https:, /, \\Optional
validateBooleanSelect 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

NameTypeDescriptionRequired
panstringThe entire credit card number.  Only in request object.Required
lastFourstringLast four digits of the credit card on fileRead Only
expirationDateobjectExpiration date of the credit card on fileRequired
expirationDate.monthstring
Required
expirationDate.yearstring
Required
cvcstringThe cvc of the card.  Only available in the token generation API calls.Required
postalCodestringThe 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
brandstringBrand of the credit card on fileRead Only
firstNamestringFirst 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
lastNamestringLast 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


Sample Request Body


This is a single representation of the PaymentToken object.  It will be used in the request bodies.  Please review individual API documentation for specific details.

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



Sample Response Body


This is a single representation of the TokenResponse object.  Please review individual API documentation for specific details.


{
    "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
}


{
    "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
    }
}